今すぐ始める

MCP サーバー

MCP クライアントから Epismo のツールとリソースを使うための設定、認証、セッション、ツールのガイドです。

Epismo MCP サーバーは、Epismo のパックとトラック操作を Model Context Protocol のツールとして公開します。AI クライアントは再利用可能なコンテキストをパックから読み、必要に応じてタスクやゴールをトラックとして作成・更新できます。さらに、現在のユーザー、プロジェクト、ユーザー、エージェントなどのコンテキストリソースを読めるため、エージェントが正しい ID とスコープを選びやすくなります。

いつ MCP を使うか

MCP は、AI クライアントに Epismo を直接操作させたいときに使います。

やりたいこと MCP が向いている理由
エージェントが必要な context pack を探す epismo_pack_search と epismo_pack_get をツールとして呼べる
エージェントが作業計画をタスクに分解する epismo_track_apply でまとめて作成できる
ChatGPT/Claude からチームのコンテキストを読む MCP リソースと OAuth によりユーザー / ワークスペースのコンテキストを維持できる
エージェントが workflow pack を更新する パック更新ツールが 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 を公開するため、クライアントはリフレッシュトークンを使ってアクセストークンを更新できます。

クライアント設定の流れは次の通りです。

  1. MCP クライアントに Epismo MCP サーバー URL を登録します。
  2. OAuth フローを開始し、mcp スコープを許可します。
  3. クライアントが initialize リクエストを送ります。
  4. サーバーがセッション ID を返します。
  5. クライアントはリソースを読んでからツールを呼びます。

セッション

最初のリクエストは 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 を使えます。workflow pack のステップ担当者は human またはエージェント ID のみです。

ペイロード例とアクセス項目の規則は リソース を参照してください。

パックツール

ツール 用途 コスト
epismo_pack_create workflow / context pack を作成 5 credits
epismo_pack_search workflow / context pack を検索 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_apply が最も使いやすいツールです。非 UUID の id を使うと、同じ呼び出しの中で依存関係を表現できます。

エージェントに探索させる場合は、まず検索条件を絞り、必要なトラックだけ詳細を取得してください。

クレジットの挙動

各ツールのコストは上の表に記載しています。クレジットは OAuth トークンで解決される現在の個人用 / ワークスペースのコンテキストから消費されます。クレジットが不足している場合、ツール呼び出しはクレジットまたは支払いのエラーとして失敗することがあります。

エイリアスツール

ツール 用途 コスト
epismo_alias_upsert 自分が所有するパックのエイリアスを作成または付け替え 1 credit
epismo_alias_list 自分の個人用とアクティブなワークスペースのエイリアスを一覧 1 credit
epismo_alias_delete エイリアスを削除 1 credit

エイリアスはパックのみを指します。トラックは UUID または UUID を含む URL で参照します。

スコープと共有

MCP の変更系ツールは API と同じアクセスモデルを使います。

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

検索ツールは個人用 / プロジェクトスコープの配列である scopes を受け取ります。変更系ツールは userIds と emails を含む sharedWith を受け取ります。更新でアクセス項目を省略すると既存レコードのアクセス設定を維持します。

このセクション内