Octri API Docs

@octri/mcp

一个 MCP 服务，可将 API 文档转换为 AI 助手可调用的工具。 Claude、Cursor、VS Code Copilot 和其他任何 MCP 客户端都可以搜索你的端点、打开指南、获取任意受支持语言的即用型 SDK 代码片段，并在同一份用于构建文档的 OpenAPI 规范中检查是否存在重大变更。

Octri 可将 OpenAPI 规范转换为文档网站、十种语言的客户端 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）使用带方括号的传输键，包括嵌套对象和数组。此机制适用于 Stripe 等将 invoice_settings 和 tax_id_data 等字段标记为 deepObject 的 API。

安装

npx -y @octri/mcp

大多数客户端都通过该命令配置，因此无需全局安装。下方的“安装”部分列出了每种客户端的准确配置代码块。

也可以一键安装。VS Code 会要求你提供项目 ID；Cursor 会将 YOUR_PROJECT_ID 写入其 mcp.json，供你替换。

已列入官方 MCP Registry，名称为 dev.octri/mcp。

工具

工具	说明
search_docs	搜索 API 文档中的端点或概念
get_endpoint	获取特定 API 端点的完整文档
list_endpoints	列出所有可用的 API 端点，也可按章节筛选
get_changelog	获取近期 API 变更和重大变更
list_sdks	列出可用的 SDK 客户端库（语言、版本、下载链接）
get_guide	根据 slug 获取书面指南的完整内容
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> 发送的 Bearer 令牌。

* 除非每次工具调用都显式传入 projectId，否则此项为必需。

被调用 API 的凭据

操作工具会调用你的真实 API，这些变量用于提供该 API 的凭据：

变量	说明
OCTRI_API_BASE_URL	操作调用的目标 API 基础 URL（默认为工作室的 Base URL）。
OCTRI_API_TOKEN	Bearer / OAuth2 令牌。
OCTRI_API_KEY（+ OCTRI_API_KEY_HEADER）	API 密钥值及其所在的标头（默认为 X-API-Key）。
OCTRI_API_USERNAME / OCTRI_API_PASSWORD	基本身份验证凭据。

以上凭据都会作为 HTTP 标头 发送。若某个 API 将凭据放在请求 正文 中（例如 Plaid 的 client_id 和 secret），则这些变量无法为其提供凭据：它们是普通的正文参数，因此会显示为工具参数，并由 Agent 像传递其他字段一样传递。为此类 API 设置 OCTRI_API_KEY 会添加一个它会忽略的标头。

权限

项目所有者会将每个操作工具设为自动运行、先询问或关闭，并从 MCP 页面发布该设置。读取操作默认自动运行，其他所有操作默认先询问。对于“先询问”的调用，系统会通过 MCP 征询机制（Claude Code 2.1.76+、VS Code）向用户显示其方法、URL 和正文，并且只有在获得批准后才会发送。无法询问的客户端会被拒绝调用。

以下设置会进一步收窄所有者允许的范围。只有 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	构建每次调用并将其返回给 Agent，不予发送。

使用情况报告

每次工具调用都会向 Octri 报告工具名称、结果、耗时和客户端名称，以便项目所有者查看 Agent 使用了哪些工具。参数和响应绝不会发送。设置 OCTRI_TELEMETRY=0 或传入 --no-telemetry 可将其关闭。

---

远程托管

使用 Streamable HTTP（MCP_TRANSPORT=http）。自 2025-03-26 版规范起，MCP 规范已将其定义为远程服务的传输方式，当前客户端也会优先尝试此方式：

docker build -t octri-mcp .

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

它提供单个端点 /mcp。客户端的首次请求会开启一个会话，并通过 mcp-session-id 标头返回会话 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，并拒绝 Origin 未列在 MCP_ALLOWED_ORIGINS 中或 Host 不是回环地址的请求。此服务持有你的 API 凭据，而浏览器访问的任何页面都能连接到回环端口。

扩大 MCP_HOST 的绑定范围会让这些凭据暴露在网络上，因此此时若未设置 MCP_AUTH_TOKEN，服务将拒绝启动；每个请求都必须发送 Authorization: Bearer <token>。请在 MCP 客户端中配置相同的请求头，并明确列出浏览器来源。

---

检查你的设置

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

确认项目及其工具已加载、基础 URL 和凭据已设置，并执行一次真实读取调用；如果出现问题，还会说明需要修复的内容。 --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 命令是服务器核心的一种宿主。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: { apiUrl, projectId }）时，静态源才会提供 Octri 的文档工具并报告用量。

---

发布

pnpm build
npm publish --access public

需要拥有可访问 @octri 作用域权限的 npm 账户。

---

Octri 的其他产品

产品	功能
API Studio	将你的 OpenAPI 规范转换为托管文档网站，提供实时请求 playground，并可逐页编辑。
SDK Studio	将同一份规范转换为十种语言的客户端库，并统一进行版本管理和发布。
MCP	基于同一份规范生成工具，让 AI 助手能够调用你的端点和文档。
Monitoring	提供 API 的错误、跟踪记录、运行时间和发布信息，并关联触达 API 的 SDK 调用。

Monitoring 运行时

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

文档 · 定价 · 更新日志

采用 MIT 许可证。