# MCP tools

Eleven Courier tools on one MCP server. Drop in the URL; your agent has a voice.

## One MCP server, fourteen tools, eleven of which are Courier

There is one Relaystation MCP server at `https://api.relaystation.ai/mcp`. Courier adds eleven tools to that server; the existing chassis tools (Baton pricing, webhook registration) sit alongside them. When you drop the Relaystation MCP URL into Cursor, Claude Code, Codex, Cline, or Continue, your agent immediately sees the full Relaystation primitive set — storage, witness, communication — all from one provider, all funded from one balance.

## The eleven Courier tools

| Tool | Channel | Blocks for reply? | Cost (above free tier) |
|---|---|---|---|
| `ask_operator(message)` | Telegram (default) | Yes (adaptive short-poll) | $0.005 |
| `ask_operator_email(message, attached_baton_id?)` | Email | Yes | $0.01 |
| `ask_operator_sms(message)` | SMS | Yes | $0.05 |
| `notify_operator(message)` | Telegram | No (fire-and-forget) | $0.005 |
| `notify_operator_email(message, attached_baton_id?)` | Email | No | $0.01 |
| `notify_operator_sms(message)` | SMS | No | $0.05 |
| `message_agent(to_address, body, attached_baton_id?)` | Internal email | No | Free |
| `create_agent_address(ttl_seconds?, purpose_label?)` | n/a | n/a | Free up to 10/day, then $0.001/mint |
| `list_my_agent_addresses()` | n/a | n/a | Free |
| `get_mailbox(address_id, since?)` | n/a | n/a | Free |
| `set_bridge_active(active)` | n/a | n/a | Free |

Each tool's MCP-manifest `description` includes cost annotation, typical reply latency, and a one-line usage example so the LLM sees the trade-off at decision time. Tool-name conventions: `ask_*` blocks for a reply (use when the agent needs the operator's answer to proceed); `notify_*` is fire-and-forget (use for status updates the operator may or may not want to acknowledge); `message_agent` is the same-network internal-mail surface.

## Install — Claude Code

In your Claude Code config (typically `~/.config/claude-code/mcp.json` or the workspace-scoped `.mcp.json`), add:

```json
{
  "mcpServers": {
    "relaystation": {
      "url": "https://api.relaystation.ai/mcp",
      "headers": {
        "Authorization": "Bearer rs_live_<your-key>"
      }
    }
  }
}
```

Restart Claude Code; the fourteen Relaystation tools appear in your agent's tool surface. Mint a key from the dashboard at [app.relaystation.ai](https://app.relaystation.ai) or via `POST /v1/account/keys`.

## Install — Cursor, Codex, Cline, Continue

The same MCP server URL applies. Each client has its own config file for MCP servers (Cursor: Settings → Features → MCP; Codex: workspace config; Cline / Continue: extension settings). The shape is the same — URL `https://api.relaystation.ai/mcp` plus the Bearer auth header carrying your `rs_live_*` key.

> **Cowork — coming soon.** Cowork's "add custom MCP server" UI accepts the server URL today, but doesn't yet expose a field for the Bearer authentication token Courier requires. Tool listings render in the picker, but tool calls fail until the auth layer lands. We've captured the gap and a fix candidate (token-in-URL support) is queued. Until then, the validated install path is Claude Code.

## Discovery

The MCP server manifest is exposed at `https://api.relaystation.ai/.well-known/mcp.json` and a Courier-scoped subset at `https://courier.relaystation.ai/.well-known/mcp.json` (eleven Courier tools with cost annotations). Agents that crawl Relaystation's domain pick up the manifest automatically; agent authors browsing the docs find it at the same URL.

## Authentication paths

Every MCP tool call must carry authentication. Three valid shapes:

- **API key.** `Authorization: Bearer rs_live_<key>` — the standard developer/agent path. Mint keys from the dashboard or via `POST /v1/account/keys`.
- **Wallet JWT.** Sign in with your wallet at `GET /v1/auth/challenge` → `POST /v1/auth/verify`; pass the returned token. Agent-friendly bearer-token path, no email needed.
- **x402 per-call payment.** For lodestone-style per-call wallets without an account. The `X-Payment` header carries an EIP-3009 authorization; no API key, no JWT. See [authentication modes](https://relaystation.ai/docs/authentication) for the full matrix.