The official Posthawk MCP server (posthawk-mcp on npm) speaks the Model Context Protocol, so any MCP-aware agent can drive your Posthawk account through tool calls. Every tool maps 1:1 to a Posthawk API endpoint and uses the official SDK under the hood — there's no wrapper to pay for, and it's free on every plan, cloud and self-hosted.

Two ways to run it

• Hosted (HTTP + OAuth 2.1) — point your agent at https://mcp.posthawk.dev/mcp. Best for Claude Code and remote agents. No API key to paste — you authorize in the dashboard via OAuth + PKCE.
• Local (stdio) — run npx posthawk-mcp as a subprocess with your API key in the environment. Best for Claude Desktop, Cursor, and Windsurf.

Your API key never crosses to the model provider. The agent only sees tool schemas and the responses to its own tool calls.

Connect Claude Code (hosted, OAuth)

claude mcp add --transport http posthawk https://mcp.posthawk.dev/mcp

The first tool call opens a browser to authorize. Approve it in the dashboard and the agent is connected — no key handling on your side.

Connect via npx (stdio)

Drop this into your client's MCP config (e.g. claude_desktop_config.json, Cursor's mcp.json):

{
  "mcpServers": {
    "posthawk": {
      "command": "npx",
      "args": ["-y", "posthawk-mcp"],
      "env": { "POSTHAWK_API_KEY": "ck_live_..." }
    }
  }
}

Connect a remote agent (HTTP + Bearer key)

For agents that call out from CI or a server, use the hosted endpoint with a raw Bearer API key instead of OAuth:

{
  "mcpServers": {
    "posthawk": {
      "url": "https://mcp.posthawk.dev/mcp",
      "headers": { "Authorization": "Bearer ck_live_..." }
    }
  }
}

Self-hosted instances

Set POSTHAWK_BASE_URL to your own worker so agents operate your infrastructure — your data never leaves your network. The same server, SDKs, and CLI all point at the same endpoints.

POSTHAWK_BASE_URL=https://api.yourdomain.com \
POSTHAWK_API_KEY=ck_live_... \
npx posthawk-mcp

Configuration

• POSTHAWK_API_KEY — your API key (required for stdio mode)
• POSTHAWK_BASE_URL — point at a self-hosted worker (optional, defaults to the cloud API)
• MCP_TRANSPORT — stdio (default) or http
• MCP_PORT — HTTP listen port (default 3002)
• MCP_SERVER_URL — public URL of the server, used in OAuth metadata
• MCP_DASHBOARD_URL — dashboard URL for the OAuth redirect (default https://app.posthawk.dev)