# MCP client configuration

{/* // WIRE THE GATE */}

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.

```bash frame="terminal"
npm install -g @postern/mcp     # or run on demand via npx
```

```bash frame="terminal"
# 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\`):

```json title="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:

```json title="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):

```bash frame="terminal"
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):

```bash frame="terminal"
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):

```json title=".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_…"
      }
    }
  }
}
```

  ```json title=".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](https://docs.agents.mszazu.com/quickstart/authentication/).

<Aside type="danger" title="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.
</Aside>

## Next

- [MCP overview & tools](https://docs.agents.mszazu.com/mcp/overview/) — the full tool list and security model.
- [wait_for_email](https://docs.agents.mszazu.com/mcp/wait-for-email/) — the blocking primitive.
- [Authentication & keys](https://docs.agents.mszazu.com/quickstart/authentication/) — scoped keys explained.