Setup

MCP client を Epismo に接続し、authentication を理解します。

AI client から Epismo を直接操作させたい場合は MCP を使います。

Transport

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

OAuth

MCP client は Authorization: Bearer <oauth_access_token> で認証します。Token には mcp scope が必要です。Server は OAuth metadata を次の path で公開します。

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

API から MCP token を issue する場合、resource には MCP server resource の absolute http または https URL を渡します。Token refresh でも refreshToken と resource が必要です。

Session lifecycle

最初の request は MCP initialize です。Server は Mcp-Session-Id を返し、client は同じ session の後続 request でその header を送ります。

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"}
    }
  }'

返ってきた Mcp-Session-Id response header を、同じ session の後続 JSON-RPC request に入れてください。Session を閉じる場合は同じ header を付けて DELETE / を送ります。

First calls

initialize の後は、mutation tool を呼ぶ前に resources を list/read します。基本の順序は次の通りです。

epismo://context/current_user で personal/workspace context を確認します。
Project scope を使う前に epismo://context/projects を読みます。
Assignee を設定する前に epismo://context/users または epismo://context/agents を読みます。
Search/get tools で既存の packs/tracks を確認します。
ID と scope が確定してから create/update/apply tools を呼びます。

この順序にすると、agent が project ID、user ID、agent ID を名前から推測する必要がなくなります。

Local development

Local MCP service は port 8080 で listen します。

npm install
npm run mcp:dev

Local run では MCP_URL、API_URL、WEB_URL、backend gRPC addresses を設定します。Hosted client は https://mcp.epismo.ai/ を使ってください。