第3章 MCP server - Kortix

MCP server通过 OAuth 或个人访问令牌，将 Claude、ChatGPT、Cursor、VS Code、Codex 或任意 MCP 客户端连接到 Kortix。一个 URL 即可访问你所有能打开的项目，无需安装任何东西。

实验性功能。工具可能会随时变更，恕不另行通知。

Kortix 提供一个托管的 MCP server： https://api.kortix.com/v1/mcp

只需将该 URL 添加到 MCP 客户端。首次调用时，浏览器会要求你登录 Kortix。之后，客户端将以你的身份、在你的权限范围内，访问你所有能打开的账户和项目——与 CLI 的作用范围相同。该 URL 不指定项目：工具通过 project_id 或 session_id 指定项目，list_projects 可列出所有项目。无需安装任何东西。

添加到客户端 除非步骤中明确说明，以下客户端首次使用时都通过 OAuth 登录。无需做任何替换：所有项目用的都是同一个 URL。

Claude Code ``` claude mcp add --transport http kortix https://api.kortix.com/v1/mcp ``` 在 Claude Code 中运行 /mcp 并登录。如需使用个人访问令牌，在命令中加上 --header "Authorization: Bearer $KORTIX_TOKEN"。

Claude Desktop 和 claude.ai Settings → Connectors → Add custom connector。粘贴 URL 并登录。

ChatGPT 自定义 MCP 连接器需要开发者模式。按 OpenAI 的 开发者模式指南， 在 Settings → Security and login 中开启 Developer mode，然后从 ChatGPT 插件页面（加号按钮）创建开发者模式应用。输入 URL 并选择 OAuth 认证。OpenAI 的套餐和菜单名称可能会有变化：如果界面标签有出入，以该指南为准。

Cursor 使用 Connect MCP 中的 Add to Cursor 按钮，或将 server 添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）： ``` { "mcpServers": { "kortix": { "url": "https://api.kortix.com/v1/mcp" } } } ```

VS Code 将 server 添加到 .vscode/mcp.json。VS Code 使用 servers 而非 mcpServers，且需要 type 字段： ``` { "servers": { "kortix": { "type": "http", "url": "https://api.kortix.com/v1/mcp" } } } ```

Codex ``` codex mcp add kortix --url https://api.kortix.com/v1/mcp codex mcp login kortix ``` 或编辑 ~/.codex/config.toml。使用个人访问令牌时，需指定存放令牌的环境变量： ``` [mcp_servers.kortix] url = "https://api.kortix.com/v1/mcp" bearer_token_env_var = "KORTIX_TOKEN" ```

其他客户端 添加一个远程（Streamable HTTP）MCP server，填入该 URL。不支持 OAuth 的客户端可通过 header 传入个人访问令牌（见下文）。

打开工作区菜单（左上角的项目名称），选择 Connect MCP，即可复制 URL 以及 Claude、Claude Code、Cursor 和 Codex 的配置步骤。

登录 该 server 使用 MCP 规范定义的 OAuth 2.1 流程，客户端无需任何配置：

不带令牌的调用会返回 401，响应头为 WWW-Authenticate: Bearer resource_metadata="…", scope="kortix"。 客户端读取 /.well-known/oauth-protected-resource/v1/mcp 处的 RFC 9728 文档，其中将 Kortix 指定为授权服务器。 客户端通过 POST /v1/oauth/register（RFC 7591）自行注册，获得一个仅用 PKCE 认证的公共客户端。 你在 Kortix 授权页面确认该客户端。自行注册的客户端会标注为 Unverified app，并显示它回调你时所用的主机。只有在你本人亲自连接时才应批准。 客户端用授权码换取 kortix_oat_ 访问令牌（1 小时）和刷新令牌（30 天，使用时轮换）。访问令牌过期后，客户端会自动刷新，无需你再次操作。

撤销客户端 Settings → Personal access keys → Connected apps 列出你批准过的所有应用（跨所有账户）：名称、登录来源和最近活跃时间。自行注册的 MCP 客户端会标注为 Unverified app。Revoke access 会删除你的批准并撤销其令牌：它的下一次请求将失败，必须重新请求你的授权。终端方式：kortix tokens apps ls 和 kortix tokens apps rm 。两者都只能在浏览器会话或个人访问令牌下使用，绝不能用应用自己的令牌。

连接的应用不能做什么 kortix 权限范围以你的身份运作：连接的应用能读取和修改你能读取和修改的内容。但它无法创建比自身可撤销令牌更持久的凭证。以下路由对 kortix_oat_ 令牌返回 403：

个人访问令牌（POST /v1/accounts/tokens）和项目 CLI 令牌； 网关密钥； SCIM 令牌； OAuth 客户端及其密钥的轮换； 服务账户； 连接的应用列表及其撤销接口（/v1/oauth/grants）。

撤销客户端后，其访问立即终止。个人访问令牌则不同：不传 --expires 就不会过期，且撤销应用不会撤销它。

个人访问令牌 不支持 OAuth 的客户端或脚本，可以改用 kortix_pat_ 令牌——即 CLI 使用的令牌。通过 kortix tokens new 或在 Settings → Personal access keys 创建，然后作为 header 传入： ``` { "mcpServers": { "kortix": { "url": "https://api.kortix.com/v1/mcp", "headers": { "Authorization": "Bearer kortix_pat_…" } } } } ```

工具 tools/list 返回 23 个工具。带 * 的参数为必填。

| 工具 | 参数 | 作用 | |---|---|---| | list_projects | 无 | 列出你在所有账户下能打开的每个项目，含 project_id 和你的角色。 | | start_session | project_id, prompt, name, agent | 在项目中启动一个会话，附带首个 prompt。返回 session_id。 | | send_message | session_id, text | 向会话排队一条消息；若会话已停止则自动启动。 | | read_session | session_id*, limit, wait_seconds | 返回会话状态（当前轮次为 idle、booting、running 或 queued）以及最新消息，包含每次工具调用的输入和输出。limit 默认 10，最大 100。wait_seconds（最长 45）可等待轮次结束。 | | list_sessions | project_id*, limit, cursor | 列出项目中你能看到的会话：id、标题、状态、agent、所有者、分支、日期。limit 默认 20，最大 200。 | | run_command | session_id*, command, cwd, timeout_seconds, job_id, cancel | 在会话沙箱中运行 bash 命令，返回 stdout、stderr 和退出码。长命令会返回一个 job_id 供继续等待。 | | read_file | path*, session_id, project_id, ref, offset, limit | 从会话沙箱读取文件，或从项目 git 仓库的 ref 处读取。图片以图片形式返回。 | | write_file | session_id, path, content*, encoding | 在会话沙箱中写文件，自动创建父目录。encoding 为 utf8（默认）或 base64。 | | list_files | path, session_id, project_id, ref, offset | 列出会话沙箱中的某个目录，或项目仓库某路径下的所有文件。 | | read_skill | name, file, project_id | 列出 Kortix 平台指南，或返回某一指南（name）或其参考文件之一（file）。传入 project_id 时，项目自身的 skills 会排在前面，项目 skill 名可返回其 SKILL.md 和参考文件路径。 | | list_connectors | project_id*, connector | 列出项目的 connectors：slug、provider、是否已连接（当前对你可用）、action 数量和账户。传入 connector 时，完整列出该 connector 的账户。 | | search_connector_actions | project_id*, query, connector, limit | 按意图查找 connector action。返回 tool（.）、risk 和一行描述。不返回 schema。 | | describe_connector_action | project_id, tool | 返回某个 action 的输入 JSON Schema、risk 和描述。 | | call_connector | project_id, tool, args, account, reason | 以你的身份执行 action。返回数据和执行账户，或带审批链接的 pending_approval 结果，或带原因的拒绝。 | | upload_connector_attachment | project_id, connector, filename*, content_base64 或 session_id + path | 暂存一个文件，返回可放入 args 的 {"$kortix_attachment": ""} 引用。 | | connect_connector | project_id, connector, owner, label | 返回一个链接，供人员打开以连接该 connector 的账户。 | | search_connector_apps | project_id, query, limit, cursor | 搜索可从中添加 connector 的托管应用目录。 | | add_connector | project_id*, app 或 provider + slug, name, url, transport, endpoint, spec, base_url | 立即向项目添加一个 connector（提交到 main 分支的 kortix.yaml，然后同步）。 | | remove_connector | project_id, connector | 从项目中移除 connector。 | | kortix | args*, project_id, session_id | 以你的身份运行真实的 kortix CLI，返回 exit_code、stdout（--json 输出则为 json）和 stderr。见“运行任意 CLI 命令”。 | | search_api | query*, limit | 按关键字搜索 Kortix API 路由。 | | describe_api | method, path | 返回单个路由的参数、请求体和响应 schema。 | | call_api | method, path, project_id, query, body | 以你的身份调用任意 /v1/ 路由。project_id 会填充路径中的 {projectId}。 |

search_api、describe_api 和 call_api 覆盖了 Web 应用和 CLI 的所有功能，因为二者都是同一 API 的客户端。call_api 拒绝 /v1/oauth/* 和任何指向 MCP 端点的路径。路径中的其他 {placeholder} 需由你自己填好。每次调用的授权和审计与来自 Web 应用的请求一致。审计以 credential_kind: "oauth_app" 和连接应用的名称记录每次调用，因为 API 记录的是它实际认证的凭证，而不是客户端声称的标签。

运行任意 CLI 命令 kortix 工具以你的身份运行真实的 kortix CLI。所有 CLI 命令都可通过它使用，因此这个 MCP server 具备与终端相同的能力：secrets、triggers、cr、review、reminders、agents、models、gateway、 providers、channels、sandboxes、apps、marketplace、files、access、roles、 permissions、audit、grants、members、groups、tokens、billing、projects、 sessions 和 system-skills。一个工具替代了约 200 个子命令工具——那样会超出 Cursor 等客户端的工具数量上限。

args 是 kortix 之后的 argv，每个参数一个数组元素，绝不是一条 shell 命令行。 ``` { "name": "kortix", "arguments": { "args": ["--help"] } } ``` ``` { "name": "kortix", "arguments": { "args": ["secrets", "ls", "--json"], "project_id": "" } } ``` ``` { "name": "kortix", "arguments": { "args": ["triggers", "ls", "--json"], "project_id": "" } } ``` ``` { "name": "kortix", "arguments": { "args": ["system-skills"] } } ```

用 ["--help"] 和 ["", "--help"] 探索命令。要解析的输出加上 --json。

project_id 为项目级命令指定项目，session_id 为作用于单个会话的命令指定会话。

结果为 JSON：exit_code、stdout、stderr。使用 --json 时，命令输出以 JSON 值的形式出现在 json 中而非 stdout。超出容量的输出会被截断并标记 truncated；被截断的 JSON 不是合法 JSON，因此应缩小命令范围。exit_code 非 0 即 MCP 错误。每个流最多保留 24,000（stdout）和 8,000（stderr）字符，结果中会以 truncated 标明。

运行超过约 45 秒的命令会被终止，结果带有 timed_out。

该 server 最多同时运行 4 条 CLI 命令，第 5 个调用返回 Busy: retry。

会话、沙箱文件和 connector 都有一等工具（start_session、run_command、read_file、call_connector），应优先使用。

CLI 在服务器上以你自己的令牌针对本 API 运行，拿不到服务器凭证：其环境中只有你的令牌、API URL、项目与会话 id，以及空的临时主目录和工作目录。命令结束后服务器会清理这两者。授权和审计由 API 负责：外部人员的令牌得到的 403 与在终端中一致。

以下命令在执行前即被拒绝，错误会说明原因和替代方案。

| 命令 | 原因 | 替代方案 | |---|---|---| | 任何 --host 或 --host= 标志、hosts | 会把 CLI 指向另一台服务器，导致你的令牌被发送到那里。本 server 已经以你的身份运作。 | 无需替代。 | | login, logout | 需要浏览器登录和存储令牌。你已通过 MCP 连接登录。 | 无需替代。 | | init, ship, deploy | 需要读写本地目录。 | 在源代码所在的会话沙箱中用 run_command。 | | apps deploy | 部署的是本地目录，而服务器上没有。 | 在会话沙箱中用 run_command 执行 kortix apps deploy 。 | | env pull, env push | 读写本地文件。 | secrets ls、secrets set KEY=value。 | | token, whoami --token-only | 会打印原始访问令牌。 | whoami --json。 | | update, uninstall, self-host | 会改动运行 CLI 的机器。 | 无。 | | tui, t, connect, attach, `sessions connect | | shell | | forward` | 交互式界面。 | 无。 | | chat 以及不带 --prompt 的 sessions chat | 打开交互式聊天。 | start_session、send_message，或加 --prompt ""。 | | connectors mcp | 启动 stdio MCP server。 | list_connectors、call_connector。 |

CLI 命令在审计中使用的凭证与该连接上的其他调用相同（credential_kind: "oauth_app"）。审计无法区分 kortix 工具和 call_api：二者都是用你的令牌访问 API。

项目 skills read_skill 传入 project_id 时，会在平台指南之前列出项目自身的 skills（仓库中的 skills//SKILL.md 文件，或旧版 .kortix/opencode/skills/）。传入 skill 名可读取其 SKILL.md 和参考文件路径，传入 file 可读取单个参考文件。你只能看到角色和权限所允许的 skills。

使用你的 connectors connector 工具就是以 MCP 工具形式呈现的 kortix connectors CLI。它们与 CLI 和 SDK 调用相同的 API 路由，因此 connector 策略、审批和审计在各端表现一致。

list_connectors 显示已连接的内容。connected: false 的 connector 无法执行 action：先调用 connect_connector，打开返回的链接，再重新 list。 search_connector_actions 按意图查找 action，例如发送邮件。describe_connector_action 返回其参数。 call_connector 执行它。结果中会注明执行账户。 connector 有多个账户且无默认值时，必须传 account。 对参数只有 id 的写操作（如 send_draft、按 id 删除）应传 reason，审批人会在真实参数旁看到它。

策略可能要求审批。此时 call_connector 返回 status: "pending_approval" 和 approval_url，由人工打开并批准。15 分钟内用相同的 tool、参数和 account 再次调用，已批准的调用会执行一次。policy_block 拒绝是最终结果。

结果超过约 40,000 字符时会返回带标记的预览（data_truncated）。缩小参数后重试。要附加文件，先用 upload_connector_attachment 暂存，再把返回的引用放入 args。Composio connector 不支持附件引用。

结果大小与分页

工具结果在 60,000 字符处截断，结尾为 …[truncated at 60000 chars]。 read_file 对长文本文件按最多约 50,000 字符分页返回。被截断的结果结尾会注明继续的 offset。offset 跳过指定行数，limit 限制返回行数。二进制文件不会以文本返回：请用 run_command 读取。 list_files 对过长的列表同样截断，传入它标注的 offset 即可。 list_sessions 在还有更多会话时返回 next_cursor，下次作为 cursor 传入。 read_session 返回最新的 limit 条消息。它会截断每条工具的输入和输出，结果放不下时会丢弃最旧的消息（omitted_older）。last_turn_error 标注失败的轮次。 单个 MCP 请求须在 55 秒内响应。带 wait_seconds 的 read_session 和仍在启动的沙箱都会在此之前停下：再次调用即可。

沙箱 带 session_id 的 run_command、read_file、write_file 和 list_files 访问的是会话的实时沙箱，与 Web 终端和文件面板的方式相同。相对路径基于 /workspace（会话的 git checkout）解析。已停止的沙箱会在首次调用时启动。沙箱中的 kortix CLI 以该会话的身份登录。只传 project_id 而不带 session_id 时，read_file 和 list_files 读取项目的 git 仓库，不会启动沙箱。

命令可以运行数分钟。单次工具调用等待约 50 秒；届时命令仍在运行，run_command 会返回 status: running、job_id 和当前已产生的输出。之后可带该 job_id 调用 run_command 继续等待，或传 cancel: true 停止它。timeout_seconds（默认 600，最大 86400）可终止运行过久的命令，退出码为 124。输出保留在沙箱的 ~/.cache/kortix-mcp/jobs// 中；工具结果只显示每个流最后 24,000 字节。沙箱停止时，其中正在运行的命令也随之终止。

该 server 是无状态的：POST 返回 JSON，GET 和 DELETE 返回 405。

与 kortix.com/mcp 不同 https://kortix.com/mcp 是另一个 server，无需登录即可提供 Kortix 公开文档和营销页面（list_public_content、 get_public_markdown），不涉及任何账户数据。要操作你的项目和会话，请使用 https://api.kortix.com/v1/mcp。