Endpoints
Authentication
Send credentials on every MCP request, including the firstinitialize:
x-api-key: <developer_api_key>, orAuthorization: Bearer <access_token>(API key or OAuth token)
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:
-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.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.
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 runtimetools/list required).
OAuth for assistant directories
For ChatGPT, Claude, Gemini, and other directory submissions:
Fetch connector metadata, which lists every manifest:
https://mcp.echozero.app/public/directory/chatgpt/ai-plugin.jsonhttps://mcp.echozero.app/public/directory/claude/connector.jsonhttps://mcp.echozero.app/public/directory/gemini/extension.json
/public/directory/{platform}/. Other platforms are listed in index.json.
See the OAuth guide for the full PKCE flow.
Assistant setup
Theez CLI (@echozero/ez on npm) runs the OAuth sign-in and wires up your client:
EchoZeroApp/skills) is not public yet. Until it is, use the CLI, OAuth or an API key.