今すぐ始める

MCP server

MCP client から Epismo tools/resources を使うための setup、auth、sessions、tools のガイドです。

Epismo MCP server は、Epismo の pack と track 操作を Model Context Protocol tools として公開します。AI client は reusable context を pack から読み、必要に応じて task/goal を track として作成・更新できます。さらに、current user、projects、users、agents などの context resources を読めるため、agent が正しい ID と scope を選びやすくなります。

いつ MCP を使うか

MCP は、AI client に Epismo を直接操作させたいときに使います。

やりたいこと MCP が向いている理由
Agent が必要な context pack を探す epismo_pack_search と epismo_pack_get を tool として呼べる
Agent が作業計画を task に分解する epismo_track_apply でまとめて作成できる
ChatGPT/Claude から team context を読む MCP resources と OAuth により user/workspace context を維持できる
Agent が workflow pack を更新する Pack update tool が PATCH semantics を持つ

Backend integration を作るなら HTTP API、手元や CI で操作するなら CLI、AI client から直接使うなら MCP という切り分けです。

Server identity and transport

  • Server name: epismo-mcp
  • Transport endpoint: Streamable HTTP JSON-RPC の POST /
  • Session close: DELETE /
  • Health checks: GET /health, GET /healthz
  • OAuth protected resource metadata: GET /.well-known/oauth-protected-resource
  • OAuth authorization server metadata: GET /.well-known/oauth-authorization-server

Authentication

MCP client は Authorization: Bearer <oauth_access_token> で認証します。Token には mcp scope が必要です。Server metadata は mcp と offline_access を advertise するため、client は refresh token を使って access token を更新できます。

Client setup の流れは次の通りです。

  1. MCP client に Epismo MCP server URL を登録します。
  2. OAuth flow を開始し、mcp scope を許可します。
  3. Client が initialize request を送ります。
  4. Server が session ID を返します。
  5. Client は resources を読んでから tools を呼びます。

Sessions

最初の request は MCP initialize です。Server は Mcp-Session-Id header を返し、同じ session の後続 request では client がその header を送ります。Session を明示的に閉じるには DELETE / を使います。

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":"curl","version":"0.1.0"}}}'

Resources

Tool call に使う ID を決める前に resources を読んでください。

URI 内容
epismo://context/current_user Current user/account/workspace JSON
epismo://context/projects 選択 workspace で accessible な projects
epismo://context/users Caller から見える workspace users
epismo://context/agents Assignment に使える installed agents

Task assignee は user ID または agent ID を使えます。Workflow pack step assignee は human または agent ID のみです。

Payload examples と access field rules は Resources を参照してください。

Pack tools

Tool 用途
epismo_pack_create Workflow/context pack を作成
epismo_pack_update UUID、alias、share URL、hub URL で pack を patch
epismo_pack_get Outline、selected nested content、full content を取得
epismo_pack_search Workflow/context pack を検索
epismo_pack_like Pack を like/unlike
epismo_pack_delete Pack と、その pack を指す自分の alias を削除

大きい pack を読むときは、まず epismo_pack_get の outline mode を使います。返ってきた contentIndex.stepIds または contentIndex.blockIds を見て、必要な nested content だけを selective fetch します。full=true は本当に全内容が必要なときだけ使います。

epismo_pack_search は credit を消費します。epismo_pack_get は、大きい pack では outline-first mode で使うと、agent が本当に必要な content だけを client 側で hydrate しやすくなります。

Tool arguments の例は Tools を参照してください。

Track tools

Tool 用途
epismo_track_create Task/goal を作成
epismo_track_update UUID/URL で task/goal を patch
epismo_track_get 1 件の track を取得
epismo_track_search Filter つきで task/goal を検索
epismo_track_apply Track を bulk create/update/delete
epismo_track_delete Track を削除

Agent が複数 task を計画する場合は epismo_track_apply が最も使いやすい tool です。非 UUID の draft ID を使うと、同じ call の中で dependency を表現できます。

epismo_track_search は credit を消費します。Agent に探索させる場合は、まず filter を絞り、必要な track だけ detail get してください。

Credit behavior

MCP では agent usage と search call が credit を消費します。Credit は OAuth token で解決される current personal/workspace context から消費されます。Credit が不足している場合、tool call は credit/payment error として失敗することがあります。

Alias tools

Tool 用途
epismo_alias_upsert 自分が所有する pack の alias を作成または付け替え
epismo_alias_delete 自分の alias を削除

Alias は pack のみを指します。Track は UUID または UUID を含む URL で参照します。

Scopes and sharing

MCP mutation tools は API と同じ access model を使います。

{ "scope": { "type": "personal" } }
{ "scope": { "type": "projects", "ids": ["project-id"] } }

Search tools は personal/project scope の array である scopes を受け取ります。Mutation tools は userIds と emails を含む sharedWith を受け取ります。Update で access field を省略すると既存 record の access settings を維持します。

Local development

Monorepo の MCP service は default で port 8080 を listen します。

npm install
npm run mcp:dev

主な environment variables は MCP_URL, API_URL, WEB_URL, backend gRPC addresses です。Production client は local development endpoint ではなく hosted MCP URL を使ってください。

このセクション内