Setup

Use MCP when an AI client should operate Epismo directly.

Transport

• Server name: epismo-mcp
• Streamable HTTP endpoint: POST /
• Session close: DELETE /
• Health checks: GET /health, GET /healthz

OAuth

MCP clients authenticate with Authorization: Bearer <oauth_access_token>. The token must include the mcp scope. The server publishes OAuth metadata at:

• GET /.well-known/oauth-protected-resource
• GET /.well-known/oauth-authorization-server

When issuing MCP tokens through the API, pass resource as the absolute http or https URL of the MCP server resource. Token refresh also requires refreshToken and resource.

Session lifecycle

The first request is MCP initialize. The server returns Mcp-Session-Id, and clients send that header on later requests in the same session.

curl -i https://mcp.epismo.ai/ \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "authorization: Bearer <token>" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{
      "protocolVersion":"2025-03-26",
      "capabilities":{},
      "clientInfo":{"name":"my-client","version":"0.1.0"}
    }
  }'

Copy the returned Mcp-Session-Id response header into later JSON-RPC requests. Send DELETE / with the same header when the client wants to close the session.

First calls

After initialize, list or read resources before mutation tools. The usual order is:

1. Read epismo://context/current_user to confirm personal vs workspace context.
2. Read epismo://context/projects before using a project scope.
3. Read epismo://context/users or epismo://context/agents before setting assignees.
4. Use search or get tools to inspect existing packs/tracks.
5. Call create/update/apply tools only after IDs and scopes are clear.

This keeps agent actions deterministic and avoids guessing project IDs, user IDs, or agent IDs from names.

Local development

The local MCP service listens on port 8080.

npm install
npm run mcp:dev

Set MCP_URL, API_URL, WEB_URL, and the backend gRPC addresses for local runs. Hosted clients should use https://mcp.epismo.ai/.