MCP

Postwind is an MCP server. It serves Streamable HTTP at /mcp on the API listener, with the same Authorization: Bearer pw_… keys and scopes as the API. There are no sessions: every request is served on its own, so any api+mcp node answers any request. Each tool wraps exactly one API operation and is named after its operationId.

Connecting

URL: http://<api-host>:8080/mcp (the path is mcp.path, default /mcp). Header: Authorization: Bearer pw_…. stdio is not supported: the server is remote and keys are mandatory. Both client lifecycles are supported: initialize (protocol versions up to 2025-11-25) and server/discover (2026-07-28).

• The API listener speaks plain HTTP and expects a TLS terminator in front of it. Behind one, the URL is https://<host>/mcp; the examples below use https://mail.example.com/mcp.
• The server issues no Mcp-Session-Id. Every POST answers application/json, so a load balancer needs no sticky sessions.
• The key is checked on every HTTP request to the path, before anything else. A bad key gets the API’s 401 problem+json, byte for byte.
• Then the Host header is checked against mcp.allowed_hosts. The default is ["localhost", "127.0.0.1", "::1"], and a host outside the list gets 403. A remote client works only after the operator adds the node’s public host name. An entry without a port allows any port; [] turns the check off.
• With mcp.enabled = false the path is not mounted and answers 404.

Client configuration

Use a project key with the scopes the agent needs, not an admin key, unless the agent has to manage projects. A key string in a config file is readable by anyone who can read the file.

Claude Code

claude mcp add --transport http postwind https://mail.example.com/mcp \
  --header "Authorization: Bearer pw_prj_…"

Add --scope user to use the server in every project, or --scope project to write it to the project’s .mcp.json. Run /mcp in Claude Code to check the connection.

Cursor

In .cursor/mcp.json of the project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "postwind": {
      "url": "https://mail.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:POSTWIND_KEY}"
      }
    }
  }
}

Cursor reads ${env:POSTWIND_KEY} from the environment, so the key string stays out of the file.

Claude Desktop

Custom connectors take a remote server by URL. A static Authorization header is set in the Request headers section of the Add custom connector dialog, with No sign-in as the authentication and Bearer pw_… as the value. That section is in beta and only some organizations have it. Claude then connects to the node itself, so the node’s MCP URL must be reachable by Claude, not only by your computer.

Without that section, use the mcp-remote bridge in claude_desktop_config.json. mcp-remote is a community bridge: a local stdio process, run with npx, that forwards to a remote server. It is not part of Postwind or of Claude Desktop.

{
  "mcpServers": {
    "postwind": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mail.example.com/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer pw_prj_…"
      }
    }
  }
}

The header value is in env because some clients do not escape spaces inside args. --transport http-only skips the SSE fallback, which Postwind does not serve.

Other clients

Any MCP client that speaks Streamable HTTP and can send a static header works: give it the URL and Authorization: Bearer pw_….

First call

Call whoami with no arguments. Your client sends initialize or server/discover first, then:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "whoami", "arguments": {} }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "<the same JSON as structuredContent>" }],
    "structuredContent": {
      "key_id": "01900000-0000-7000-8000-000000000001",
      "name": "ops",
      "kind": "project",
      "project_id": "<project_id>",
      "scopes": ["read", "write"],
      "expires_at": null
    },
    "isError": false
  }
}

The answer tells the key’s kind, its project, its scopes and its expiry: the same body as GET /api/v1/whoami. Then get_server_info returns the node’s version, enabled subservices and transports.

Keys and project context

A project key works in its own project; the project_id argument is ignored. An admin key must pass project_id to project tools.

• Project tools are the tools of operations under /api/v1/projects/{project_id}/…. Their project_id argument is optional in the schema.
• With a project key the argument is ignored entirely, even when it is not a UUID.
• With an admin key and no argument the call fails with validation_failed, field project_id, code required. A value that is not a UUID is not_found.
• get_project, update_project_settings and delete_project require project_id from every key and check it as the API checks its path: another project is not_found.

After that the checks are those of the API; see Authentication and scopes.

Tool rules

Every description answers three questions in order: Call it … (when), Needs … (key, scope, state), Returns … (what comes back). Arguments are strict: an unknown argument is validation_failed. Output is structuredContent, field for field the body of the API operation, plus a text block with the same JSON.

The full rules, with the error shape and the limits, are on Tool rules.

Confirm and dry run

launch_campaign, cancel_campaign, revoke_api_key, revoke_admin_key, delete_project, delete_list, delete_sending_domain, erase_subscriber, add_suppression and remove_suppression need confirm: true. Without it the tool checks everything the real call checks, says what would happen (outcome, effect) and writes nothing.

confirm defaults to false, so a call that leaves it out is always a dry run. Run the dry run first, show its effect to a person when it matters, then call again with confirm: true.

Errors

isError: true with code and detail from the same table as the API, plus errors for validation_failed and precondition_failed.

The codes are on the API errors page. The rate limit (429) and the body limit (413) are answered at the HTTP level, as in the API; they are not tool errors.

Limits

Lists return up to 100 items (limit 1–100, default 50) with the same cursor as the API. import_subscribers takes up to 1 000 records per call; larger imports go through the API. There is no Idempotency-Key: a tool that got no answer is checked with the matching list_* tool before it is called again.

Requests share the key’s rate limit with the API, and every JSON-RPC message counts. See Rate limits.

Resources

• postwind://docs/templates — template syntax and variables
• postwind://docs/deliverability — the deliverability checklist
• postwind://docs/errors — the error codes

The resources are built into the binary.