MCP サーバー
MCP クライアントから Epismo のツールとリソースを使うための設定、認証、セッション、ツールのガイドです。
Epismo MCP サーバーは、Epismo のパックとトラック操作を Model Context Protocol のツールとして公開します。AI クライアントは再利用可能なコンテキストをパックから読み、必要に応じてタスクやゴールをトラックとして作成・更新できます。さらに、現在のユーザー、プロジェクト、ユーザー、エージェントなどのコンテキストリソースを読めるため、エージェントが正しい ID とスコープを選びやすくなります。
いつ MCP を使うか
MCP は、AI クライアントに Epismo を直接操作させたいときに使います。
| やりたいこと | MCP が向いている理由 |
|---|---|
| エージェントが必要な コンテキスト・パックを探す | epismo_pack_search と epismo_pack_get をツールとして呼べる |
| エージェントが作業計画をタスクに分解する | epismo_track_apply でまとめて作成できる |
| ChatGPT/Claude からチームのコンテキストを読む | MCP リソースと OAuth によりユーザー / ワークスペースのコンテキストを維持できる |
| エージェントが ワークフロー・パックを更新する | パック更新ツールが PATCH 方式を持つ |
バックエンド連携を作るなら HTTP API、手元や CI で操作するなら CLI、AI クライアントから直接使うなら MCP という切り分けです。
サーバーの識別情報とトランスポート
- サーバー名:
epismo-mcp - トランスポートエンドポイント: Streamable HTTP JSON-RPC の
POST / - セッション終了:
DELETE / - ヘルスチェック:
GET /health,GET /healthz - OAuth 保護リソースのメタデータ:
GET /.well-known/oauth-protected-resource - OAuth 認可サーバーのメタデータ:
GET /.well-known/oauth-authorization-server
認証
MCP クライアントは Authorization: Bearer <oauth_access_token> で認証します。トークンには mcp スコープが必要です。サーバーメタデータは mcp と offline_access を公開するため、クライアントはリフレッシュトークンを使ってアクセストークンを更新できます。
クライアント設定の流れは次の通りです。
- MCP クライアントに Epismo MCP サーバー URL を登録します。
- OAuth フローを開始し、
mcpスコープを許可します。 - クライアントが
initializeリクエストを送ります。 - サーバーがセッション ID を返します。
- クライアントはリソースを読んでからツールを呼びます。
セッション
最初のリクエストは MCP initialize です。サーバーは Mcp-Session-Id ヘッダーを返し、同じセッションの後続リクエストではクライアントがそのヘッダーを送ります。セッションを明示的に閉じるには DELETE / を使います。
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":"curl","version":"0.1.0"}}}'リソース
ツール呼び出しに使う ID を決める前にリソースを読んでください。
| URI | 内容 |
|---|---|
epismo://context/current_user |
現在のユーザー / アカウント / ワークスペースの JSON |
epismo://context/projects |
選択ワークスペースでアクセス可能なプロジェクト |
epismo://context/users |
呼び出し元から見えるワークスペースユーザー |
epismo://context/agents |
割り当てに使えるインストール済みエージェント |
タスク担当者にはユーザー ID またはエージェント ID を使えます。ワークフロー・パックのステップ担当者は human またはエージェント ID のみです。
ペイロード例とアクセス項目の規則は リソース を参照してください。
パックツール
| ツール | 用途 | コスト |
|---|---|---|
epismo_pack_create |
ワークフロー / コンテキストを作成 | 5 credits |
epismo_pack_search |
ワークフロー / コンテキストを検索 | 5 credits |
epismo_pack_get |
アウトライン、指定したネスト内容、全文を取得 | 1 credit |
epismo_pack_update |
UUID、エイリアス、共有 URL、ハブ URL でパックを更新 | 1 credit |
epismo_pack_like |
パックをいいね / 解除 | 1 credit |
epismo_pack_delete |
パックと、そのパックを指す自分のエイリアスを削除 | 1 credit |
大きいパックを読むときは、まず epismo_pack_get のアウトラインモードを使います。返ってきた contentIndex.stepIds または contentIndex.blockIds を見て、必要なネスト内容だけを取得します。full=true は本当に全内容が必要なときだけ使います。
ツール引数の例は ツール を参照してください。
トラックツール
| ツール | 用途 | コスト |
|---|---|---|
epismo_track_search |
フィルターつきでタスク/ゴールを検索 | 2 credits |
epismo_track_create |
タスク/ゴールを作成 | 1 credit |
epismo_track_update |
UUID/URL でタスク/ゴールを更新 | 1 credit |
epismo_track_get |
1件のトラックを取得 | 1 credit |
epismo_track_apply |
トラックを一括作成 / 更新 / 削除 | 1 credit |
epismo_track_delete |
トラックを削除 | 1 credit |
epismo_track_review |
レビューを生成 | AI token usage |
エージェントが複数タスクを計画する場合は epismo_track_apply が最も使いやすいツールです。非 UUID の id を使うと、同じ呼び出しの中で依存関係を表現できます。
エージェントに探索させる場合は、まず検索条件を絞り、必要なトラックだけ詳細を取得してください。
タスク完了後、またはゴールの completed/postponed 後に epismo_track_review を使うと、1件以上の対象、関連トラック、ログ、元パックから読み取り専用のレビューを生成できます。詳細レビューは、内部で使った AI token usage に基づいて credits を消費します。
ログツール
| ツール | 用途 | コスト |
|---|---|---|
epismo_log_create |
トラックにログ/コメントを残す | free |
epismo_log_list |
ログを一覧取得 — 1トラック、または全トラック横断 | 1 credit |
epismo_log_delete |
ログを 1 件削除 | free |
ログは、トラック自身のフィールドを変えずに、活動、コメント、レビュー記録をトラックへ紐づけます。
クレジットの挙動
各ツールのコストは上の表に記載しています。クレジットは OAuth トークンで解決される現在の個人用 / ワークスペースのコンテキストから消費されます。クレジットが不足している場合、ツール呼び出しはクレジットまたは支払いのエラーとして失敗することがあります。
エイリアスツール
| ツール | 用途 | コスト |
|---|---|---|
epismo_alias_upsert |
自分が所有するパックのエイリアスを作成または付け替え | 5 credits |
epismo_alias_get |
単一のエイリアスをパックに解決 | 1 credit |
epismo_alias_list |
自分の個人用とアクティブなワークスペースのエイリアスを一覧 | 2 credits |
epismo_alias_delete |
エイリアスを削除 | 1 credit |
エイリアスはパックのみを指します。トラックは UUID または UUID を含む URL で参照します。
改善案ツール
| ツール | 用途 | コスト |
|---|---|---|
epismo_suggestion_create |
パックの所有者に改善案を送信 | 5 credits |
epismo_suggestion_get |
1件の改善案を取得(任意でスナップショット付き) | 1 credit |
epismo_suggestion_list |
送信済み / 受信 / パック単位の改善案を一覧 | 2 credits |
epismo_suggestion_update |
自分の改善案を更新 | 1 credit |
epismo_suggestion_resolve |
自分が所有する改善案のステータスを変更 | 1 credit |
改善案はパックに対するテキスト中心の提案です。パックを読める人なら誰でも作成でき、更新できるのは投稿者だけ、解決できるのはパックの所有者だけです。パラメータは [ツール](/ja/docs/mcp/tools# 改善案ツール) を参照してください。
スコープと共有
MCP の変更系ツールは API と同じアクセスモデルを使います。
{ "scope": { "type": "personal" } }{ "scope": { "type": "projects", "ids": ["project-id"] } }検索ツールは個人用 / プロジェクトスコープの配列である scopes を受け取ります。変更系ツールは userIds と emails を含む sharedWith を受け取ります。更新でアクセス項目を省略すると既存レコードのアクセス設定を維持します。