使用文档MCP 接入

MCP 接入

配置 MCP 连接,让 Codex、Claude Desktop、Cursor 等客户端访问项目。

连接前的准备

准备一个可以通过 HTTPS 访问的 Feronavi 实例,以及该实例签发的 API 令牌。在产品的 API 令牌页面创建令牌,先选择只读档位,验证读取后再按任务需求开放写入。

令牌所属账号、项目范围、IP 限制、到期时间和撤销状态都会影响可用能力。示例中的 https://feronavi.example.com 和 fero_xxx 都需要替换。

选择连接方式

Feronavi MCP 端点为 /api/v1/mcp,支持 Streamable HTTP。支持远程 MCP 的客户端可以直接配置此 URL 和 Bearer 认证。

需要本地 stdio 的客户端可使用 feronavi-mcp 桥。运行桥接包的机器需安装 Node.js 20 或更新版本,以及 npm;不需要下载 Feronavi 源码。桥只负责协议转发,工具说明来自服务端,不缓存业务数据。

npx -y feronavi-mcp@0.1.0 --url https://feronavi.example.com --token fero_xxx

feronavi-mcp 已发布到 npm。当前版本为 0.1.0,也可以在终端直接验证命令:

npx -y feronavi-mcp@0.1.0 --help

配置客户端时可固定到已验证版本,便于控制升级时间。

Claude Desktop 与 Cursor

Claude Desktop 配置文件和 Cursor 的 .cursor/mcp.json 使用以下 mcpServers 结构。令牌只保存在本地配置或受保护的环境变量中。

{
  "mcpServers": {
    "feronavi": {
      "command": "npx",
      "args": ["-y", "feronavi-mcp@0.1.0"],
      "env": {
        "FERONAVI_URL": "https://feronavi.example.com",
        "FERONAVI_TOKEN": "fero_xxx"
      }
    }
  }
}

VS Code

在 .vscode/mcp.json 中使用 servers 结构:

{
  "servers": {
    "feronavi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "feronavi-mcp@0.1.0"],
      "env": {
        "FERONAVI_URL": "https://feronavi.example.com",
        "FERONAVI_TOKEN": "fero_xxx"
      }
    }
  }
}

Codex 与其他客户端

在 ~/.codex/config.toml 中添加以下配置,然后在 Codex 中重新连接 MCP:

[mcp_servers.feronavi]
command = "npx"
args = ["-y", "feronavi-mcp@0.1.0"]

[mcp_servers.feronavi.env]
FERONAVI_URL = "https://feronavi.example.com"
FERONAVI_TOKEN = "fero_xxx"

把示例地址和令牌替换为自己的实例信息。其他客户端可按其当前版本的 MCP 配置入口添加远程服务器,或将桥接命令作为 stdio 服务;不同客户端的外层配置字段不同,不要直接复制另一客户端的配置。

连接后先让 Agent 发现工具、列出可访问项目,再读取一个明确项目的工作项,确认实例、身份和范围正确。

查询和修改项目

可以从这样的请求开始:

检查本次迭代的未完成事项,按负责人梳理风险。先给出建议,经过我确认再修改状态和指派,完成后重新读取并核对。

Agent 使用平台业务服务,遵循同一套权限规则。外部客户端负责自己的规划和确认交互;建议在客户端明确要求修改前确认。内置知识助手则在产品界面提供建议确认流程。

排查连接失败

  • 检查客户端所在机器是否能访问 HTTPS 端点。
  • 检查令牌是否有效、已到期、被撤销或受到 IP 限制。
  • 检查令牌档位与项目白名单是否允许当前任务。
  • 对写入结果不明确的请求,先查询当前数据,再决定是否重试。

输入关键词,搜索全部使用文档。