MCP Getting Started

Postcards exposes a public Model Context Protocol (MCP) server so you can plug any MCP-compatible AI agent — Claude Desktop, Cursor, Continue, Zed, custom clients — straight into your email projects. Once connected, your agent can list projects, inspect folders, check your plan and quota, and export ready-to-use HTML on its own, using only your existing Postcards API key.

In this article we'll show you what MCP is, why you might want it, and how to get an agent talking to Postcards in under five minutes.

Important: The MCP server is a thin, read-only-plus-export proxy on top of the Postcards API. Anything an agent can do through MCP, you could also do directly with HTTP requests — MCP just makes it dramatically more natural for AI tools.

What is MCP?

The Model Context Protocol is an open standard (released by Anthropic in late 2024) for connecting AI assistants to external tools and data. Instead of you copy-pasting API responses into a chat, the AI agent calls real tools on your behalf and gets structured results back.

In practice that means you can say:

"Show me my latest 10 Postcards projects."

"Export project 305876 as HTML, replace {{username}}    with Alex, and give me the result."

"How many exports do I have left this month?"

…and the agent does it. No screen-sharing, no copying URLs, no manually building curl commands.

What's in the box

The Postcards MCP server exposes six tools:

All six are read-only or one-way export — nothing on your account can be deleted, renamed, or moved through MCP.

1. Get a Postcards API key

The MCP server uses your existing Postcards API key — there's no separate sign-up.

1. In Postcards, open Workspace Settings → API Keys.
2. Click Create new key, name it (e.g. "Claude Desktop"), and copy the raw key. It looks like sk-pcds-api03-...    and is shown only once.

If you already have a key for the REST API, you can reuse it — same key, both endpoints. Full instructions: Get Started with the Postcards API.

2. Add Postcards to your AI client

The MCP endpoint is:

https://mcp-postcards.designmodo.com/mcp

Different clients have slightly different config formats. Below are the two common shapes — pick whichever your client accepts.

Option A — Stdio bridge (works with every client)

This is the safe default. It uses mcp-remote   , a tiny Node helper that proxies your client's stdio to our HTTP endpoint. You don't install anything — npx    downloads it on first use.

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json    (macOS), %APPDATA%\Claude\claude_desktop_config.json    (Windows), or the equivalent on Linux:

{
  "mcpServers": {
    "postcards": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp-postcards.designmodo.com/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH}"
      ],
      "env": { "AUTH": "Bearer sk-pcds-api03-XXXXXXXXXXXXXXXXXXXXXXXX" }
    }
  }
}

Restart Claude Desktop. The postcards    server should appear in the tools panel with six tools listed.

Important: The ${AUTH}    indirection isn't cosmetic — mcp-remote    splits the --header    value on the first colon, so a value containing a space (like Bearer sk-...   ) needs to come from an env var. Don't paste your key directly into args   .

Option B — Native HTTP (newer clients)

Some clients (Cursor ≥ 0.42, recent Claude Desktop, Zed, ChatGPT custom connectors) speak Streamable HTTP directly. In those, the config is simpler:

{
  "mcpServers": {
    "postcards": {
      "type": "http",
      "url": "https://mcp-postcards.designmodo.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-pcds-api03-XXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

If your client rejects this with "Server is missing the required 'command' field", it doesn't support native HTTP yet — fall back to Option A.

3. Talk to your agent

Once connected, just ask in plain English. Your agent will pick the right tool, run it, and show you the results.

List your projects:

"List my Postcards projects."

Filter by folder:

"What projects are in the Newsletters folder?"

Export a project as HTML:

"Export project 305876 as HTML with image hosting enabled."

Personalize with variables:

"Export project 305876 and replace {{username}}    with Alex and {{company}}    with Acme."

Check your usage:

"How many Postcards exports do I have left this month?"

The agent decides which tool to call based on the natural-language request — you don't need to know the tool names.

4. How exports work over MCP

postcards_export_project    accepts the same options as the REST API and returns one of three shapes depending on imageHosting    and format   :

Full parameter list

Why the 5 MB cap on ZIP?

MCP transports the result inline as text. Large binaries in a chat panel get unwieldy quickly. For bulk ZIP exports, call POST /api/v1/projects/{id}/export    over plain HTTPS instead — see the API docs.

5. Pagination

Two of the MCP tools return paginated results — exactly mirroring the REST API.

Both accept the same two optional parameters:

The tool result always includes a meta    block describing the current position:

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 537,
    "total_pages": 11
  }
}

Telling the agent to walk all pages

Most agents handle this automatically when you ask for "all projects" or "everything in the Newsletters folder" — they keep calling the tool with incrementing page    until page > meta.total_pages   . If your client doesn't do that on its own, ask explicitly:

"List all my Postcards projects across every page."

Important: Don't ask the agent to fetch hundreds of pages in one go without need. Each page is a separate API call and burns through your read rate limit (60 requests/min). For 500+ projects, prefer per_page=100    to halve the number of round-trips.

6. Security and privacy

A few things worth knowing:

• The MCP server stores nothing. Your API key arrives in the Authorization    header of every request and is forwarded to the REST API. It's never logged, never persisted, never cached.
• All checks happen on the REST side. Team scoping, plan gating, export quota, rate limits — the MCP layer is transparent.
• Rate limits still apply. 60 read requests/min, 10 exports/min per API key. If your agent goes wild, you'll get a rate_limit_exceeded    error and a Retry-After    hint.
• Revoke instantly. If you suspect a key leaked, delete it from Team Settings → API Keys — the next MCP call with that key will return 401 unauthorized   .

Important: Treat the API key like a password. Avoid pasting it into shared screens, version-controlled repos, or chat transcripts you'll share publicly.

7. Troubleshooting

"Server is missing the required 'command' field" Your client only accepts stdio configs. Switch to Option A above.

"Connection closed" right after start Your client probably tried the deprecated SSE transport. Add --transport http-only    to the mcp-remote    args.

"Invalid API key" or 401 Double-check the bearer token. Common mistakes: extra whitespace, missing the Bearer    prefix when not using env var indirection, or pasting the masked preview (sk-pcds-api03-abc...xyz   ) instead of the full raw key.

Tool call returns plan_required    The feature you asked for (e.g. CDN hosting) isn't on your team's plan. Upgrade, or call the tool without that option.

Tool call returns export_limit_exceeded    You've used all monthly exports on your plan. Run postcards_get_usage    to confirm, and either wait for the period to roll over or upgrade.