MCP

同じ API を、シナリオではなくアシスタントに向けたもの。MCP クライアントは実行中にツールの説明から何を呼ぶかを選ぶので、届く範囲はその資格情報が届く範囲とちょうど同じで、どのツールの下にも公開 API の呼び出しがあります。

エンドポイントはひとつ

すべて POST /v1/mcp に送ります。開くセッションも保持するストリームもありません。GET と DELETE は 405 を返し、各メッセージがそれぞれのリクエストです。

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

2025-03-26 から 2026-07-28 までのプロトコル改訂はすべて応答します。initialize で始めるクライアントには期待どおりのハンドシェイクを、リクエストごとにバージョンを示すクライアントにはその方式で応じます。

APIキーでつなぐ

いちばん速い方法で、自分で動かすツールにはこれが正解です。どのキーも bearer トークンとして働き、提示されるツールはそのキーのスコープに切り詰められます。

多くのクライアントは次のようなブロックを受け取ります：

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

OAuth でつなぐ

人がキーに一切触れない、他社のディレクトリ上のコネクタ向けです。ディスカバリは RFC 9728 と RFC 8414 に従い、クライアントは RFC 7591 で自ら登録し、すべての認可は S256 の PKCE を使います。

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

認可のない呼び出しは、どこへ行き何を求めるかを自ら告げます：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

承認する人は Mosaqo にサインインしており、どのワークスペースに適用するかを選び、自分がオーナーまたは管理者である場所でのみそれができます——API キーを発行できる人を決めるのと同じ線です。あとから Bulk & API で接続を解除できます。

アシスタントにできること

すでにご存じのスコープそのままです。資格情報が許さないツールは tools/list に載らず、名前を指定しても呼べません。ですからどの接続でも、生きた答えは tools/list そのものです。

スコープ	許可される操作
`qr:read`	QRコード、フォルダ、テンプレートの一覧取得と読み取り
`qr:write`	作成、更新、リンク先変更、公開、アーカイブ、削除
`exports:read`	レンダリング済みカードのダウンロード
`analytics:read`	集計アナリティクスと個々のスキャン
`bulk:write`	一括ジョブの作成と読み取り
`webhooks:write`	Webhookサブスクリプションの管理
`reviews:read`	場所、アンケート、その状況 — 回答そのものは含まない

決して届かないもの

アンケートに人が書いた内容。 reviews:read は場所、アンケート、その状況を開きます——件数、スコア、設問ごとの分布です。訪問者が打った文そのものは、ここでも、資格情報の届くどこでも返しません。feedback.* イベントがスコアを運び、言葉を決して運ばないのと同じ理由です。

コードの削除。 REST のルートは入力による確認を求めます。印刷されたコードの背後にあるリダイレクトを壊すことは取り消せず、それは誰かに代わってアシスタントが与える確認ではないからです。代わりにアーカイブがあり、こちらは戻せます。

書き込みは書き込みとして印されています。何かを変えるツールは readOnlyHint: false を、アーカイブは destructiveHint: true を持ちます——クライアントが実行前に立ち止まって人に尋ねるのは、これがあるからです。