> ## Documentation Index
> Fetch the complete documentation index at: https://docs.echozero.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI assistants to Echo Zero via Model Context Protocol (Streamable HTTP).

Echo Zero exposes an [MCP](https://modelcontextprotocol.io/) server so Claude, ChatGPT, Cursor, and other assistants can call tools, read resources, and use prompts on behalf of authenticated users.

<Warning>
  `https://mcp.echozero.app/mcp` is a **JSON-RPC POST endpoint**, not a web page. Opening it in a browser (GET) returns an error. Configure your MCP client to send `POST` requests instead.
</Warning>

## Endpoints

| Surface               | URL                                          | Method                     |
| --------------------- | -------------------------------------------- | -------------------------- |
| MCP (Streamable HTTP) | `https://mcp.echozero.app/mcp`               | `POST`                     |
| MCP SSE stream        | `https://mcp.echozero.app/mcp/sse`           | `GET` (after `initialize`) |
| End session           | `https://mcp.echozero.app/mcp`               | `DELETE`                   |
| Directory metadata    | `https://mcp.echozero.app/public/index.json` | `GET`                      |

## Authentication

Send credentials on **every** MCP request, including the first `initialize`:

* `x-api-key: <developer_api_key>`, or
* `Authorization: Bearer <access_token>` (API key or [OAuth token](/guides/oauth))

Optional REST HMAC headers (`x-signature`, `x-timestamp`) also apply when your API key has a secret. See [API keys + HMAC](/guides/api-keys-hmac).

## Session lifecycle

<Steps>
  <Step title="Initialize">
    `POST /mcp` with `method: "initialize"`. Save the `mcp-session-id` response header.
  </Step>

  <Step title="Send initialized notification">
    `POST /mcp` with `method: "notifications/initialized"` and the session header.
  </Step>

  <Step title="Call tools / list resources">
    Include `mcp-session-id: <session>` on all subsequent requests.
  </Step>

  <Step title="Optional SSE stream">
    `GET /mcp/sse` with `Accept: text/event-stream` and the session header for server-push events.
  </Step>

  <Step title="End session">
    `DELETE /mcp` with the session header when done.
  </Step>
</Steps>

<Warning>
  Sessions are **bound to the credential** used at `initialize`. Using a different API key or OAuth token with the same `mcp-session-id` returns **403** (JSON-RPC `-32002`).
</Warning>

Response headers may also include `X-Mcp-Instance-Id` for load-balancer sticky routing in multi-instance deployments.

## Example `initialize` request

```bash theme={null}
curl -sS https://mcp.echozero.app/mcp \
  -H "x-api-key: $EZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'
```

Save `mcp-session-id` from the response headers.

## Example `tools/list`

```bash theme={null}
curl -sS https://mcp.echozero.app/mcp \
  -H "x-api-key: $EZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $MCP_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'
```

## Tools, resources, and scopes

Available MCP tools, resources, and prompts are **scope-gated** by the API key or OAuth token. Common scopes:

| Scope                                  | Capability               |
| -------------------------------------- | ------------------------ |
| `read:agents` / `write:agents`         | Agent management tools   |
| `read:wallet` / `write:wallet`         | Wallet and balance tools |
| `read:strategies` / `write:strategies` | Strategy configuration   |
| `read:trades`                          | Trade and signal history |
| `read:tokens`                          | Token metadata           |
| `write:ai`                             | AI chat tools            |

Tools forward to the same REST endpoints documented in the API Reference. Errors use JSON-RPC format — see [Error codes](/guides/error-codes).

## OAuth for assistant directories

For ChatGPT, Claude, Gemini, and other directory submissions:

| Setting       | Value                                          |
| ------------- | ---------------------------------------------- |
| MCP URL       | `https://mcp.echozero.app/mcp`                 |
| Authorize URL | `https://mcp.echozero.app/oauth/authorize`     |
| Token URL     | `https://mcp.echozero.app/oauth/token`         |
| Scopes        | From `/public/directory/{platform}/` manifests |

Fetch connector metadata:

```
https://mcp.echozero.app/public/index.json
```

See the [OAuth guide](/guides/oauth) for the full PKCE flow.

## Assistant setup shortcut

```bash theme={null}
npx skills add EchoZeroApp/skills-draft
ez login
```

Installs Echo Zero skills and runs the PKCE browser flow against `https://mcp.echozero.app`. See the [OAuth guide](/guides/oauth) for manual integration.