MCPサーバーリファレンス

認証

MCPのエンドポイントにはBearerトークンが必要です。EmDashは次のトークンの取得方法に対応しています。

セッションのCookieでは、MCPのエンドポイントの認証はできません。

スコープ

OAuthのトークンと個人用アクセストークンは、クライアントが呼び出せるツールを制限します。ユーザーのロールは別に確認されるため、スコープによって、ユーザーが持っていない権限が与えられることはありません。

認可コードの同意画面では、ユーザーは要求されたスコープを外せます。EmDashは、要求されたスコープを、クライアントに登録されたスコープとユーザーのロールとも照らし合わせて絞り込み、何も許可されない結果になった場合は拒否します。

必要なロール

次の表は、大まかな操作ごとに必要な最小のロールを示しています。ユーザーが別のユーザーのコンテンツを操作する場合は、所有者の確認によって、より上位のロールが必要になることがあります。

ロールの定義全体については、ユーザーのロールを参照してください。

通信方式

このサーバーは、ステートレスなStreamable HTTPを使います。各リクエストは独立しており、サーバーはMCPのセッションもServer-Sent Eventsの接続も保持しません。

レスポンスにはJSON-RPC 2.0を使います。ツールのリクエストを組み立てる前に、tools/list を呼び出して、現在の入力スキーマとMCPのアノテーションを取得します。

ツールの一覧

次の一覧は、tools/list が返す静的なツールと一致しています。クライアントによってはツール名の代わりに登録タイトルを表示するため、登録タイトルも載せています。

コンテンツのツール

バイラインのツール

スキーマのツール

メディアのツール

検索のツール

タクソノミーのツール

メニューのツール

リビジョンのツール

設定のツール

ツールのスキーマの使い方

tools/list は、各ツールの説明、JSONの入力スキーマ、アノテーションを返します。呼び出しを組み立てる前にこのメタデータを読み、インストールされているEmDashのバージョンが対応するフィールド、使える値、制限をクライアントが使うようにします。

たとえば、記事を更新するクライアントは、まず content_get を呼び出し、返された _rev を保持します。そのうえで、次のJSON-RPCのリクエストを送れます。

{
	"jsonrpc": "2.0",
	"id": 2,
	"method": "tools/call",
	"params": {
		"name": "content_update",
		"arguments": {
			"collection": "articles",
			"id": "01JARTICLE0000000000000000",
			"data": { "title": "Updated title" },
			"_rev": "opaque-revision-token"
		}
	}
}

結果は、最初のコンテンツブロックにJSONのテキストとして返されます。出力スキーマを持つツールは、同じ値を structuredContent にも入れて返す場合があります。

コンテンツのライフサイクルとバイライン

content_get は、中身を解釈しない _rev の値を返します。この値を content_update、content_publish、content_unpublish、content_discard_draft に渡します。古い値を渡すと競合が返されるため、再試行する前にエントリーを読み込み直します。

content_update は部分的な更新です。指定しなかったフィールドは現在の値のままです。公開済みのエントリーを更新すると、公開中の版はそのままで、下書きが用意されます。content_compare で公開中の値と下書きの値を確認し、content_publish を呼び出して下書きを公開するか、content_discard_draft を呼び出して下書きを削除します。content_delete はエントリーをゴミ箱に移します。ゴミ箱のエントリーを完全に削除するのは content_permanent_delete だけです。

バイラインは、再利用できる執筆者や協力者のクレジットです。byline_create は、ゲストのクレジットを作成することも、バイラインをCMSのユーザーに結び付けることもできます。返されたバイラインのIDを、content_create と content_update が受け取る入力 bylines に渡します。バイラインを削除すると、そのクレジットはコンテンツから外れ、主なバイラインに設定されていた場合はその設定も解除されます。

MCPでの書き込みは、管理画面のエントリーの編集ロックの対象になりません。_rev の確認は、それを受け取る操作を保護しますが、ほかの書き込みツールは、編集者がエントリーを開いている間でもエントリーを変更できます。

翻訳

コンテンツ、バイライン、タクソノミーのターム、メニューの翻訳のツールは、該当する翻訳グループのすべてのロケールの版を返します。作成のツールのスキーマに translationOf の入力がある場合は、それを使います。必須のフィールドは tools/list が正です。

content_translations は、コレクションと、コンテンツのIDまたはスラッグを受け取ります。バイライン、タクソノミーのターム、メニューの翻訳のツールは、1件のレコードのIDか、共有の翻訳グループのIDのどちらかを受け取ります。下書きにアクセスできないユーザーには、公開済みのコンテンツの翻訳だけが表示されます。

スキーマ、メディア、タクソノミー、メニュー

スキーマのツールは、データベースの構造を変更します。コンテンツを作成したりフィールドを変更したりする前に、schema_get_collection を使います。このツールは、使えるフィールド名、型、制約、検証ルールを返します。コレクションとフィールドを削除すると、保存されたコンテンツやフィールドの値も削除され、元に戻せません。

base64でエンコードしたバイト列を送る場合や、公開されたHTTPまたはHTTPSのURLから取得する場合は、media_upload を使います。URLからのアップロードでは、プライベートネットワークの宛先は拒否され、リダイレクトも改めて確認されます。media_create は、指定したストレージキーにファイルがすでにあり、そのメタデータを登録する必要がある場合にだけ使います。アップロードには設定されたサイズとMIMEタイプの制限が適用されます。同じバイト列の場合は、既存のメディアが deduplicated: true 付きで返されることがあります。

タクソノミーの定義は、分類と、その分類を適用するコレクションを記述します。タームは、コンテンツに割り当てる個々の値です。階層を持つタームは parentId を使えますが、親は同じタクソノミーに属している必要があり、循環を作ることはできません。子を持つタームを削除する前に、その子を削除するか移動する必要があります。

menu_set_items は、メニューの項目のリスト全体を、1回の不可分な操作で置き換えます。配列の順序がメニューの順序になります。入れ子になった項目の parentIndex は、同じ配列の中の前にある項目を指すため、すべての親をその子より前に置きます。

media_usage_repair は、1つのコレクションまたはすべてのコレクションを処理でき、大きなサイトでは長時間かかる場合があります。complete、partial、failed、stale のステータスは、いずれもツールの成功のレスポンスです。isError に頼らず、返されたステータスと件数を確認します。認証、検証、予期しない実行時の失敗では isError: true が設定されます。

プラグインのツール

各プラグインのMCPの機能は、管理者が有効にする必要があります。有効にしたツールは、tools/list に <pluginId>__<localName> として表示され、トークンで認証した呼び出しには mcp:tools または mcp:tools:<pluginId> が必要です。EmDashは、プラグインのルートが宣言している権限も確認し、プラグイン、ツール、ルート、実行者を監査ログに記録します。

プラグインのツールはインストールごとに異なるため、上の静的な一覧には含まれていません。

OAuthの検出

MCPクライアントは、保護対象リソースのメタデータから認可サーバーを検出します。

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

レスポンスは、/_emdash/api/mcp を保護対象のリソースとして示し、認可サーバーへのリンクを含みます。クライアントは次に、そのメタデータを次の場所から読み込みます。

GET /.well-known/oauth-authorization-server/_emdash

このドキュメントは、現在の認可、トークン、登録、デバイス認可の各エンドポイントと、対応するスコープ、グラントの種類、PKCEの方式 S256 を提供します。OAuthのプロトコルのルートをハードコードせず、検出した値を使います。

認証されていないMCPのリクエストには、検出用のURLを含む 401 のレスポンスが返されます。

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://example.com/.well-known/oauth-protected-resource"

エラー

ツールが失敗すると isError: true になります。最初のテキストブロックは変わらないコードで始まり、構造化されたメタデータを読むクライアントのために、_meta.code にも同じコードが入ります。

{
	"content": [{ "type": "text", "text": "[NOT_FOUND] Collection 'articles' not found" }],
	"isError": true,
	"_meta": { "code": "NOT_FOUND" }
}

認証の失敗には、INSUFFICIENT_SCOPE や INSUFFICIENT_PERMISSIONS などのコードが使われます。通信の失敗にはJSON-RPCの内部エラーのコード -32603 が使われ、内部で発生した例外の内容は公開されません。