# MCP server

Connect AI agents to Paragraph via the Model Context Protocol.

The Paragraph MCP server lets AI agents interact with Paragraph directly. Manage posts, publications, subscribers, coins, and more from any MCP-compatible client.

This page is about giving your AI tools (Claude Code, Cursor, and so on) access to Paragraph's API. If you want the opposite (connecting external tools to your Paragraph agent so it can use them), see [agent connections](https://docs.paragraph.com/agent/connections).

## [Quick start](https://docs.paragraph.com/developers/mcp#quick-start)

The fastest way to get started is with the hosted server at `mcp.paragraph.com`. No installation or API key management needed. You authenticate through your Paragraph account in the browser.

```bash
claude mcp add paragraph --transport http https://mcp.paragraph.com/mcp
```

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "paragraph": {
      "url": "https://mcp.paragraph.com/mcp"
    }
  }
}
```

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "paragraph": {
      "url": "https://mcp.paragraph.com/mcp"
    }
  }
}
```

Add to `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "paragraph": {
      "url": "https://mcp.paragraph.com/mcp"
    }
  }
}
```

## [Local server](https://docs.paragraph.com/developers/mcp#local-server)

If you prefer to run the server locally, use npx. Requires Node.js 18+.

```bash
npx @paragraph-com/mcp
```

The server runs over stdio and works with any MCP client.

```bash
claude mcp add paragraph -- npx @paragraph-com/mcp
```

To include your API key:

```bash
claude mcp add --env PARAGRAPH_API_KEY=your-key paragraph -- npx @paragraph-com/mcp
```

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "paragraph": {
      "command": "npx",
      "args": ["@paragraph-com/mcp"],
      "env": {
        "PARAGRAPH_API_KEY": "your-key"
      }
    }
  }
}
```

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "paragraph": {
      "command": "npx",
      "args": ["@paragraph-com/mcp"],
      "env": {
        "PARAGRAPH_API_KEY": "your-key"
      }
    }
  }
}
```

Add to `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "paragraph": {
      "command": "npx",
      "args": ["@paragraph-com/mcp"],
      "env": {
        "PARAGRAPH_API_KEY": "your-key"
      }
    }
  }
}
```

## [Authentication](https://docs.paragraph.com/developers/mcp#authentication)

The remote server at `mcp.paragraph.com` handles authentication automatically. When you first connect, you'll be redirected to approve access through your Paragraph account in the browser.

For the local server, the MCP server resolves your API key in this order:

1. **`PARAGRAPH_API_KEY` environment variable** (highest priority)
2. **Shared CLI config** at `~/.paragraph/config.json` (set via `npx @paragraph-com/cli login`)

Get your API key in the app at [app.paragraph.com](https://app.paragraph.com/) under **Settings -> Publication -> Developer**.

Read-only tools like search, feed, and public post fetching work without authentication. You only need to authenticate for write operations and accessing your own publication data.

## [Available tools](https://docs.paragraph.com/developers/mcp#available-tools)

The server exposes 18 tools organized into toolsets:

| Toolset        | Tools                                                                              | Auth required         |
|----------------|------------------------------------------------------------------------------------|-----------------------|
| **posts**      | `get-post`, `list-posts`, `create-post`, `update-post`, `delete-post`, `send-test-email` | Write ops only        |
| **publications**| `get-publication`                                                                | No                    |
| **subscribers** | `list-subscribers`, `get-subscriber-count`, `add-subscriber`                     | Yes                   |
| **users**      | `get-user`                                                                        | No                    |
| **coins**      | `get-coin`, `list-coin-holders`                                                  | No                    |
| **search**     | `search-posts`, `search-blogs`, `search-coins`                                   | No                    |
| **feed**       | `get-feed`                                                                        | No                    |
| **me**         | `get-me`                                                                          | Yes                   |

## [Filtering toolsets](https://docs.paragraph.com/developers/mcp#filtering-toolsets)

Expose only the tools your agent needs to reduce context usage:

```bash
npx @paragraph-com/mcp --toolsets posts,search
```

Available toolset names: `posts`, `publications`, `subscribers`, `users`, `coins`, `search`, `feed`, `me`

## [HTTP mode](https://docs.paragraph.com/developers/mcp#http-mode)

For server deployments, run the MCP server over HTTP instead of stdio:

```bash
npx @paragraph-com/mcp --http --port 3100
```

The HTTP server binds to `127.0.0.1` (localhost only) and accepts POST requests. A health check is available at `GET /health`.

## [Resources](https://docs.paragraph.com/developers/mcp#resources)

[**View on GitHub**  
Explore the source code or report issues.](https://github.com/paragraph-xyz/paragraph-mcp) [**npm package**  
View on npm.](https://www.npmjs.com/package/@paragraph-com/mcp)  
[CLI  
Manage posts, publications, subscribers, and coins from the command line. Built for humans, agents, and CI.](https://docs.paragraph.com/developers/cli)  
[Agent skills  
Installable skills that teach any AI agent how to use the Paragraph API, CLI, SDK, and MCP server.](https://docs.paragraph.com/developers/agent-skills)