MCP server

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.

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.

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

Add to your claude_desktop_config.json:

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

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

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

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

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

Local server

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

npx @paragraph-com/mcp

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

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

To include your API key:

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

Add to your claude_desktop_config.json:

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

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

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

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

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

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:

PARAGRAPH_API_KEY environment variable (highest priority)
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 under Settings → API keys.

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

The server exposes 33 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
content	`create-content`, `list-content`, `get-content`, `update-content`, `archive-content`, `restore-content`	Yes
buckets	`list-content-buckets`, `get-content-bucket`, `get-post-content-bucket`, `create-post-content-bucket`	Yes
publications	`get-publication`, `update-publication`	Write ops only
subscribers	`list-subscribers`, `get-subscriber-count`, `add-subscriber`, `remove-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
analytics	`analytics-query`, `analytics-schema`	Yes
emails	`send-custom-email`	Yes

The content tools draft short-form pieces (X posts and threads, LinkedIn posts, one-off emails, X Articles) into the publication's library. They never send: the writer does that in the app.

The buckets tools group a post with everything made out of it, so a repurposing run produces one stacked row under Content instead of unrelated drafts. See Drafted content.

Both are set with update-post after the draft exists. create-post doesn't accept them.

Email subscribers without publishing online. Call update-post with publishOnline: false, status: "published", and sendNewsletter: true. Subscribers receive the email, and the post never appears on your website, feed, or RSS. Its URL returns 404, so the tool result has no publicUrl. The post reads back as publishOnline: false with a publishedAt timestamp and status: "draft", since it has no live page. To put it on your site later, send publishOnline: true together with status: "published", and leave out sendNewsletter so subscribers aren't emailed a second time.
Cross-post with a canonical URL. If a post first appeared elsewhere, call update-post with canonicalUrl set to the original URL. Paragraph puts it in the page's canonical metadata so search engines credit the original. The Paragraph link keeps working and the newsletter still sends. Pass null to clear it.

Agents connected to the server get this guidance automatically, so a prompt like "email this to subscribers but don't publish it" or "republish this from my old blog with the canonical pointing there" does the right thing.

Filtering toolsets

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

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

Available toolset names: posts, content, buckets, publications, subscribers, users, coins, search, feed, me, analytics, emails

HTTP mode

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

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.

Quick start

Local server

Authentication

Available tools

Filtering toolsets

HTTP mode

Resources

View on GitHub

npm package

On this page