セットアップ

MCP クライアントを Epismo に接続し、認証の仕組みを理解します。

AI クライアントから Epismo を直接操作させたい場合は MCP を使います。

トランスポート

サーバー名: epismo-mcp
Streamable HTTP エンドポイント: POST /
セッション終了: DELETE /
ヘルスチェック: GET /health, GET /healthz

OAuth

MCP クライアントは Authorization: Bearer <oauth_access_token> で認証します。トークンには mcp スコープが必要です。サーバーは OAuth メタデータを次のパスで公開します。

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

API から MCP トークンを発行する場合、resource には MCP サーバーリソースの絶対 http または https URL を渡します。トークン更新でも refreshToken と resource が必要です。

セッションのライフサイクル

最初のリクエストは MCP initialize です。サーバーは Mcp-Session-Id を返し、クライアントは同じセッションの後続リクエストでそのヘッダーを送ります。

curl -i https://mcp.epismo.ai/ \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "authorization: Bearer $EPISMO_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 レスポンスヘッダーを、同じセッションの後続 JSON-RPC リクエストに入れてください。セッションを閉じる場合は同じヘッダーを付けて DELETE / を送ります。

最初の呼び出し

initialize の後は、変更系ツールを呼ぶ前にリソースを一覧 / 読み取りします。基本の順序は次の通りです。

epismo://context/current_user で個人用 / ワークスペースのコンテキストを確認します。
プロジェクトスコープを使う前に epismo://context/projects を読みます。
担当者を設定する前に epismo://context/users または epismo://context/agents を読みます。
検索 / 取得ツールで既存のパック / トラックを確認します。
ID とスコープが確定してから作成/更新/適用ツールを呼びます。

この順序にすると、エージェントがプロジェクト ID、ユーザー ID、エージェント ID を名前から推測する必要がなくなります。

どこに接続するか

MCP クライアントをホスト済みサーバーに向けます。

https://mcp.epismo.ai/

自分で何かをインストールしたり起動したりする必要はありません。MCP サーバーは Epismo がホストしています。この URL をクライアントに登録し、mcp スコープで OAuth を完了したら、上の initialize リクエストから始めます。