MCP client configuration

The Postern MCP server runs two ways: stdio for local hosts (the host spawns the process) and hosted HTTP (you connect to a running deployment). Pick the snippet for your host.

Try it with zero setup

Drop POSTERN_API_KEY and add "POSTERN_MOCK": "1" to any snippet below. The server boots against deterministic fixtures, so you can click through every tool — including wait_for_email — fully offline, no key, no network.

Install & build

Requires Node ≥ 18.18.

npm install -g @postern/mcp     # or run on demand via npx

# stdio — for local hosts
postern-mcp

# hosted — MCP Streamable HTTP at POST /mcp (default :8787)
postern-mcp --http --port 8787

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

claude_desktop_config.json

{
  "mcpServers": {
    "postern": {
      "command": "npx",
      "args": ["-y", "@postern/mcp"],
      "env": {
        "POSTERN_API_BASE_URL": "https://api.agents.mszazu.com",
        "POSTERN_API_KEY": "pk_agent_…"
      }
    }
  }
}

Running from a local checkout instead of npm:

claude_desktop_config.json (local checkout)

{
  "mcpServers": {
    "postern": {
      "command": "node",
      "args": ["/absolute/path/to/postern/mcp/dist/bin.js"],
      "env": { "POSTERN_API_KEY": "pk_agent_…" }
    }
  }
}

Claude Code

Add the server with one command (stdio):

claude mcp add postern \
  --env POSTERN_API_BASE_URL=https://api.agents.mszazu.com \
  --env POSTERN_API_KEY=pk_agent_… \
  -- npx -y @postern/mcp

Or connect to a hosted deployment over HTTP (pass your scoped key as a bearer header):

claude mcp add --transport http postern https://api.agents.mszazu.com/mcp \
  --header "Authorization: Bearer pk_agent_…"

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

stdio

.cursor/mcp.json

{
  "mcpServers": {
    "postern": {
      "command": "npx",
      "args": ["-y", "@postern/mcp"],
      "env": {
        "POSTERN_API_BASE_URL": "https://api.agents.mszazu.com",
        "POSTERN_API_KEY": "pk_agent_…"
      }
    }
  }
}

hosted HTTP

.cursor/mcp.json

{
  "mcpServers": {
    "postern": {
      "url": "https://api.agents.mszazu.com/mcp",
      "headers": { "Authorization": "Bearer pk_agent_…" }
    }
  }
}

What key to use

Use a scoped agent key (pk_agent_…) or an enrollment key (pk_enroll_…) — never an org-wide credential. With an enrollment key, the host’s first move is redeem_enrollment, which mints the agent key it then uses. See Authentication & keys.

Don't put a master key in host config

Host config files are easy to leak (synced dotfiles, screen shares, support bundles). Put only a short-lived, single-purpose enrollment key there. If it leaks, revoke it — instantly and in isolation — without touching any other agent.

Next

• MCP overview & tools — the full tool list and security model.
• wait_for_email — the blocking primitive.
• Authentication & keys — scoped keys explained.