Octri API Docs

@octri/mcp

API ドキュメントを、AI アシスタントが呼び出せるツールに変換する MCP サーバーです。 Claude、Cursor、VS Code Copilot、その他あらゆる MCP クライアントから、ドキュメントの生成元と同じ OpenAPI spec を使って、エンドポイントを検索したり、ガイドを開いたり、サポートされている言語のすぐに使える SDK スニペットを取得したり、破壊的変更について変更履歴を確認したりできます。

Octri は OpenAPI spec を、ドキュメントサイト、10 言語対応のクライアント SDK、AI アシスタントが呼び出せる MCP サーバー、そしてそれらを支える API のモニタリングに変換します。このパッケージは MCP サーバーです。詳しくはoctri.dev/mcpをご覧ください。

Node 20 以降が必要です。ローカルクライアント向けには stdio 経由で、ホストする場合は Streamable HTTP 経由で動作します。

操作の本文には、ドキュメントに記載されているメディアタイプを使用します。multipart またはバイナリの値には、サイズ制限のあるインライン記述子のみを渡してください。 { "filename": "report.csv", "content": "base64...", "contentType": "text/csv" }。 パスと URL は意図的にサポートされていません。

明示的に指定された URL エンコードの deepObject フィールドで explode: true を使用する場合、ネストされたオブジェクトや配列を含め、ブラケット形式のワイヤーキーを使用します。これは、invoice_settings や tax_id_data などのフィールドを deepObject として指定する Stripe などの API に対応しています。

インストール

npx -y @octri/mcp

ほとんどのクライアントはこのコマンドで設定できるため、グローバルインストールは任意です。各クライアントの正確な設定ブロックについては、以下のインストールセクションをご覧ください。

または、ワンクリックでインストールできます。VS Code ではプロジェクト ID の入力を求められます。Cursor は mcp.json に YOUR_PROJECT_ID を書き込むので、置き換えてください。

公式 MCP Registry に dev.octri/mcp として登録されています。

ツール

ツール	説明
search_docs	エンドポイントまたは概念について API ドキュメントを検索します
get_endpoint	特定の API エンドポイントの完全なドキュメントを取得します
list_endpoints	利用可能なすべての API エンドポイントを一覧表示します。セクションで絞り込むこともできます
get_changelog	最近の API の変更と破壊的変更を取得します
list_sdks	利用可能な SDK クライアントライブラリ（言語、バージョン、ダウンロードリンク）を一覧表示します
get_guide	スラッグで指定したガイドの全文を取得します
get_sdk_methods	サポートされているすべての言語で、各エンドポイントのすぐに使える SDK コードスニペットを取得します

---

インストール

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "my-api-docs": {
      "command": "npx",
      "args": ["@octri/mcp", "--project-id", "YOUR_PROJECT_ID"]
    }
  }
}

Cursor

プロジェクトのルートにある .cursor/mcp.json（またはグローバル設定の ~/.cursor/mcp.json）に追加します。

{
  "mcpServers": {
    "my-api-docs": {
      "command": "npx",
      "args": ["@octri/mcp"],
      "env": {
        "OCTRI_PROJECT_ID": "YOUR_PROJECT_ID"
      }
    }
  }
}

VS Code（Copilot / MCP 拡張機能）

.vscode/mcp.json に追加します。

{
  "servers": {
    "my-api-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["@octri/mcp", "--project-id", "YOUR_PROJECT_ID"]
    }
  }
}

---

環境変数

変数	必須	デフォルト	説明
OCTRI_PROJECT_ID	はい*	なし	接続するプロジェクトです。--project-id CLI フラグでも設定できます。
OCTRI_API_URL	いいえ	https://api.octri.dev/api/v1	ローカル開発または認可されたプライベートテスト用エンドポイントで、API のベース URL を上書きします。Octri のセルフホストには対応していません。
MCP_TRANSPORT	いいえ	stdio	リモートホスティングには http（Streamable HTTP）、またはレガシートランスポートには sse を指定します。
PORT	いいえ	3000	http および sse トランスポート用の HTTP ポートです。
MCP_HOST	いいえ	127.0.0.1	バインドするインターフェースです。範囲を広げるには MCP_AUTH_TOKEN が必要です。
MCP_ALLOWED_ORIGINS	いいえ	なし	HTTP トランスポートへのアクセスを許可するブラウザーオリジンを、カンマ区切りで指定します。
MCP_AUTH_TOKEN	MCP_HOST がループバックでない場合	なし	すべての HTTP リクエストで Authorization: Bearer <token> として送信する必要があるベアラートークンです。

* すべてのツール呼び出しで projectId を明示的に渡す場合を除き、必須です。

呼び出す API の認証情報

操作ツールは実際の API を呼び出し、以下の環境変数で認証情報を指定します。

変数	説明
OCTRI_API_BASE_URL	操作呼び出しの対象となる API のベース URL です（設定されていない場合は、studio の Base URL が使われます）。
OCTRI_API_TOKEN	ベアラー／OAuth2 トークンです。
OCTRI_API_KEY（および OCTRI_API_KEY_HEADER）	API キーの値と、送信先のヘッダーです（デフォルトは X-API-Key）。
OCTRI_API_USERNAME / OCTRI_API_PASSWORD	Basic 認証の認証情報です。

これらはすべて HTTP ヘッダーとして送信されます。代わりにリクエストの body に認証情報を指定する API（たとえば Plaid の client_id と secret）には使用できません。これらは通常の body フィールドなので、ツール引数として表示され、エージェントは他のフィールドと同様に渡します。このような API に OCTRI_API_KEY を設定しても、無視されるヘッダーが追加されるだけです。

権限

プロジェクトの所有者は、各操作ツールを自動実行、事前確認、または無効に設定し、その設定を MCP ページから公開します。読み取りはデフォルトで自動実行され、それ以外はすべて事前確認が必要です。「事前確認」の呼び出しでは、MCP の elicitation を通じて（Claude Code 2.1.76 以降、VS Code）、メソッド、URL、body がユーザーに表示され、承認された場合にのみ送信されます。確認を求められないクライアントでは、呼び出しは拒否されます。

これらの設定は、所有者が許可した範囲をさらに狭めます。範囲を広げるのは ALLOW のみで、所有者が無効にしたツールを復活させるものはありません。

変数	フラグ	効果
OCTRI_READ_ONLY=1	--read-only	読み取りツールのみを一覧表示し、実行します。
OCTRI_DENY_TOOLS=a,b	--deny-tools a,b	これらのツールを一覧表示も実行もしません。
OCTRI_ALLOW_TOOLS=a,b	--allow-tools a,b	これらの「事前確認」が必要なツールを確認なしで実行します（すべてを対象にする場合は *）。
OCTRI_ALLOW_WRITES=1	--allow-writes	OCTRI_ALLOW_TOOLS=* と同じです。
OCTRI_DRY_RUN=1	--dry-run	各呼び出しを組み立て、送信せずにエージェントへ返します。

使用状況の報告

各ツール呼び出しでは、ツール名、結果、所要時間、クライアント名が Octri に報告されるため、プロジェクトの所有者はエージェントがどのツールを使用しているかを確認できます。引数と応答は送信されません。無効にするには OCTRI_TELEMETRY=0 を設定するか、--no-telemetry を渡します。

---

リモートホスティング

Streamable HTTP（MCP_TRANSPORT=http）を使用します。これは、MCP 仕様でリビジョン 2025-03-26 以降、リモートサーバー向けに定義されているトランスポートであり、現在のクライアントが最初に試すものです。

docker build -t octri-mcp .

docker run -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e OCTRI_PROJECT_ID=YOUR_PROJECT_ID \
  octri-mcp

単一のエンドポイント /mcp を提供します。クライアントは最初のリクエストでセッションを開き、その ID を mcp-session-id ヘッダーで受け取ります。以降の各リクエストにはその ID が含まれ、同じサーバーに到達します。これにより、事前確認が必要なツールが機能します。承認プロンプトは呼び出しの途中で送信され、回答は別のリクエストで返されます。30 分間アイドル状態のセッションは終了します。レプリカが複数ある場合は、mcp-session-id によってルーティングし、スティッキーセッションを使用してください。リモート MCP クライアントの接続先には http://your-host:3000/mcp を指定します。

レガシー HTTP+SSE トランスポート

MCP_TRANSPORT=sse は、既存のデプロイメントとの互換性を保つため、旧来の 2024-11-05 方式を提供します。接続を開く GET /sse と、クライアントのメッセージを中継する POST /messages?sessionId=<id> を公開します。新たに利用する場合は http を推奨します。

バインドとオリジン

どちらの HTTP トランスポートも、デフォルトでは 127.0.0.1 にバインドし、MCP_ALLOWED_ORIGINS に含まれていない Origin を持つリクエスト、または Host がループバックではないリクエストを拒否します。このサーバーは API 認証情報を保持するため、ブラウザーでアクセスするページはどれもループバックポートに接続できます。

MCP_HOST の範囲を広げると、ネットワーク上に認証情報が公開されるため、MCP_AUTH_TOKEN が設定されていない場合、サーバーは起動を拒否します。また、すべてのリクエストで Authorization: Bearer <token> を送信する必要があります。MCP クライアントにも同じヘッダーを設定し、ブラウザーのオリジンを明示的に一覧に指定してください。

---

セットアップを確認する

npx -y @octri/mcp doctor --project-id YOUR_PROJECT_ID

プロジェクトとそのツールが読み込まれること、ベース URL と認証情報が設定されていることを確認し、実際の読み取り呼び出しを 1 回実行して、失敗した場合は修正方法を示します。 --no-call を指定すると、呼び出しをスキップします。失敗時はゼロ以外の終了コードで終了します。

---

ローカル開発

# Build
pnpm build

# Run in stdio mode
OCTRI_PROJECT_ID=my-project node dist/index.js

# Run in Streamable HTTP mode (POST /mcp)
MCP_TRANSPORT=http OCTRI_PROJECT_ID=my-project node dist/index.js

# Run in the legacy SSE mode
MCP_TRANSPORT=sse OCTRI_PROJECT_ID=my-project node dist/index.js

ライブラリとして

octri-mcp コマンドは、サーバーコアをホストする方法の 1 つです。createServer にはツールソースと、ホスト側で決定するその他すべての要素を渡します。

import { createServer, startStdio, processEnv, loadUserPermissions } from "@octri/mcp";

const env = processEnv("ACME"); // reads ACME_API_TOKEN, ACME_ALLOW_TOOLS, ...
await startStdio(() =>
  createServer({
    // "live" fetches tools from the Octri API; "static" serves a fixed manifest.
    source: { kind: "static", manifest },
    branding: { name: "acme-mcp", version: "2.4.0" },
    env,
    permissions: loadUserPermissions(process.argv.slice(2), env),
  }),
);

静的ソースは Octri のドキュメントツールを提供し、Octri プロジェクト（octri: { apiUrl, projectId }）が渡された場合にのみ、使用状況を報告します。

---

公開

pnpm build
npm publish --access public

@octri スコープへのアクセス権を持つ npm アカウントが必要です。

---

Octri のその他の製品

製品	内容
API Studio	OpenAPI 仕様から、ページごとに編集可能な、ライブリクエストプレイグラウンド付きのホスト型ドキュメントサイトを作成します。
SDK Studio	同じ仕様から、10 言語のクライアントライブラリを作成し、まとめてバージョン管理してリリースします。
MCP	同じ仕様から、AI アシスタントが呼び出せるツールとして、エンドポイントとドキュメントを生成します。
Monitoring	API のエラー、トレース、稼働時間、リリースを、API に到達した SDK 呼び出しと関連付けます。

Monitoring のランタイム

Node · Python · Go · Ruby · Rust · PHP · Java · Kotlin · Swift · Dart

ドキュメント · 料金 · 変更履歴

MIT ライセンス。