Skip to main content
EchoZero exposes an MCP server so Claude, ChatGPT, Cursor, and other assistants can call tools, read resources, and use prompts on behalf of authenticated users.
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.

Endpoints

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)
MCP accepts OAuth bearer tokens, which need no request signing. How an API key behaves on MCP is being confirmed: REST calls with an API key need x-timestamp and x-signature (see API keys + HMAC), but do not rely on either behaviour for MCP yet. Use an OAuth token if you want a documented path. A request with no credential gets a JSON-RPC error, not the REST envelope:
An unknown key gets -32001 with Invalid or expired API key. See Error codes.

Session lifecycle

1

Initialize

POST /mcp with method: "initialize". Save the mcp-session-id response header.
2

Send initialized notification

POST /mcp with method: "notifications/initialized" and the session header.
3

Call tools / list resources

Include mcp-session-id: <session> on all subsequent requests.
4

Optional SSE stream

GET /mcp/sse with Accept: text/event-stream and the session header for server-push events.
5

End session

DELETE /mcp with the session header when done.
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).
Response headers may also include X-Mcp-Instance-Id for load-balancer sticky routing in multi-instance deployments.

Example initialize request

The examples use an OAuth access token (OAUTH_TOKEN, from the OAuth flow or npx @echozero/ez login), which needs no request signing. API-key behaviour on MCP is being confirmed, so prefer the OAuth token. The signing rules for REST are in API keys and HMAC.
Save mcp-session-id from the response headers.

Example tools/list

Tools, resources, and scopes

Available MCP tools, resources, and prompts are scope-gated by the API key or OAuth token. The full scope list is in Authentication overview; MCP tools maps tool families to scopes. Tools forward to the same REST endpoints documented in the API Reference. Errors use JSON-RPC format - see Error codes. See the full Tools Reference and Resources for the out-of-band catalog (no runtime tools/list required).

OAuth for assistant directories

For ChatGPT, Claude, Gemini, and other directory submissions: Fetch connector metadata, which lists every manifest:
The manifests are individual files, for example:
  • https://mcp.echozero.app/public/directory/chatgpt/ai-plugin.json
  • https://mcp.echozero.app/public/directory/claude/connector.json
  • https://mcp.echozero.app/public/directory/gemini/extension.json
There is no index page at /public/directory/{platform}/. Other platforms are listed in index.json. See the OAuth guide for the full PKCE flow.

Assistant setup

The ez CLI (@echozero/ez on npm) runs the OAuth sign-in and wires up your client:
The skills pack (EchoZeroApp/skills) is not public yet. Until it is, use the CLI, OAuth or an API key.