JustOneAPI MCP Server 使用教程：让 AI 助手直接查找和调用数据接口

MCP 是什么

MCP，全称是 Model Context Protocol，可以把外部工具、数据源和 API 以统一方式接入到 AI 客户端。对开发者来说，它的价值不是多一个概念，而是让 AI 助手可以按工具协议完成真实操作。

JustOneAPI MCP Server 会把 Just One API 的接口目录、参数说明和调用能力暴露给支持 MCP 的客户端。接入后，你可以直接在 ChatGPT、Codex、Cursor、Hermes Agent 或其他兼容客户端里用自然语言询问接口、确认参数，并在补齐必要参数后调用对应 API。

JustOneAPI MCP 能解决什么问题

• 不需要先在文档里逐个翻接口，AI 可以根据自然语言需求查找候选接口。
• 不需要凭记忆猜参数，AI 会先查看接口 schema，再告诉你必填参数、枚举值和调用方式。
• 不需要手写每一次请求，AI 可以在你完成授权并提供业务参数后调用接口。
• 可以继续处理分页结果，例如让 AI 根据上一次返回的下一页提示继续获取数据。
• 可以查询账户余额、最近调用量和消费情况，便于调试和排查。
• 可以辅助解释常见返回码，比如参数错误或业务状态码。

选择认证方式

ChatGPT 和 Codex 推荐使用 OAuth。配置 https://mcp.justoneapi.com/mcp 后，客户端会在连接流程或首次调用需要授权的工具时提示打开 JustOneAPI 授权页；登录后选择要绑定的 API Token 并批准即可。账户 Owner 可以选择现有 Token 或创建专用 Token，Token Member 只能使用分配给自己的固定 Token。OAuth 方式不需要把 API Token 粘贴进客户端，JustOneAPI 侧也不需要额外开启功能开关。

不支持 MCP OAuth 的客户端仍可使用现有 API Token，通过 Authorization: Bearer your_token 请求头连接。只有这种兼容方式和本地 stdio 需要手动配置 Token。Token 是敏感信息，不要把真实 Token 写进公开仓库、公开截图或发给不可信的人。

支持哪些客户端

JustOneAPI MCP 推荐使用 Streamable HTTP 远程接入。目前本文提供以下接入方式：

• ChatGPT 自定义 MCP 连接，使用 OAuth。
• Codex CLI 和 Codex IDE 扩展，使用 OAuth。
• Cursor 和 Hermes Agent，使用现有 API Token 兼容方式。
• 支持远程 HTTP MCP server 和自定义请求头的其他客户端，使用现有 API Token 兼容方式。
• Claude.ai、Claude Desktop 和 Claude Code 的 OAuth 接入仍在兼容性测试中；Claude Code 可以继续使用现有 API Token 请求头。

所有远程客户端都使用同一个 MCP 地址，但认证方式取决于客户端支持的 OAuth 注册方式、账号或工作区策略，以及是否支持自定义请求头。下面只把已经验证的 OAuth 路径列为推荐方式。

通用连接信息

• MCP 地址：https://mcp.justoneapi.com/mcp
• 推荐认证：OAuth，在浏览器中登录 JustOneAPI 并批准连接。
• 兼容认证：Authorization: Bearer your_token。

如果客户端不支持 OAuth，但支持常见的 mcpServers JSON 结构和自定义请求头，可以参考下面的兼容配置：

{
  "mcpServers": {
    "justoneapi": {
      "url": "https://mcp.justoneapi.com/mcp",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

配置完成后，重启或刷新 MCP 客户端。这个 JSON 示例只适用于现有 API Token 兼容方式；OAuth 客户端不要填写静态 Authorization 请求头。

按客户端接入

ChatGPT Web

目前可以通过 ChatGPT Developer mode 添加并测试自定义 MCP 连接：

• 打开 Settings → Security and login，启用 Developer mode。
• 打开 ChatGPT Plugins 页面，点击 + 新增连接。
• 填写名称和说明，Server URL 使用 https://mcp.justoneapi.com/mcp。
• Authentication 选择 OAuth，不要填写静态 API Token 或 Authorization 请求头。
• 创建连接后，在连接流程或首次调用需要授权的工具时，按提示登录 JustOneAPI、选择要绑定的 API Token 并批准授权。

Developer mode 是否可见可能取决于 ChatGPT 账号和工作区策略。JustOneAPI 生产环境已启用 OAuth，无需额外设置。具体入口以 OpenAI 官方连接测试说明 为准。

Codex

Codex 推荐使用 OAuth。先添加远程 MCP server，再显式使用已经验证的 DCR 注册方式登录：

codex mcp add justoneapi \
  --url https://mcp.justoneapi.com/mcp

codex mcp login justoneapi \
  --oauth-client-registration dcr

浏览器打开 JustOneAPI 授权页后，登录、选择要绑定的 API Token 并批准。然后运行下面的命令确认配置：

codex mcp get justoneapi

ChatGPT 桌面端、Codex CLI 和 Codex IDE 扩展会读取同一台 Codex 主机上的 MCP 配置。更多配置说明请查看 OpenAI MCP 官方文档。

Claude Code（API Token 兼容方式）

Claude.ai、Claude Desktop 和 Claude Code 的 OAuth 接入仍在兼容性测试中，暂不列为正式支持的 OAuth 连接方式。Claude Code 可以通过自定义 Authorization 请求头使用现有 API Token：

claude mcp add \
  --transport http \
  --scope user \
  --header "Authorization: Bearer your_token" \
  justoneapi https://mcp.justoneapi.com/mcp

添加后运行下面的命令检查配置：

claude mcp get justoneapi

启动 Claude Code 后，可以输入 /mcp 确认 JustOneAPI 已连接。不要把真实 Token 提交到项目配置或仓库。更多配置说明请查看 Claude Code MCP 官方文档。

Cursor

先为启动 Cursor 的进程设置环境变量：

export JUSTONEAPI_TOKEN="your_token"

然后把下面的配置写入全局配置文件 ~/.cursor/mcp.json。如果文件中已有 mcpServers，只需合并 justoneapi 子项。

{
  "mcpServers": {
    "justoneapi": {
      "url": "https://mcp.justoneapi.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:JUSTONEAPI_TOKEN}"
      }
    }
  }
}

保存后重新启动 Cursor，打开侧边栏的 Customize 页面，确认 JustOneAPI MCP 已启用并且工具可见。Cursor 必须能够读取上面设置的环境变量；如果从终端设置，可以从同一终端启动 Cursor。更多配置说明请查看 Cursor MCP 官方文档。

Hermes Agent

Hermes Agent 原生支持远程 HTTP MCP server。为了避免把 Token 直接写入配置文件，先将 JustOneAPI Token 保存到 Hermes 默认的环境变量文件 ~/.hermes/.env：

JUSTONEAPI_TOKEN=your_token

然后把下面的配置加入 ~/.hermes/config.yaml。如果文件中已经有 mcp_servers，只需合并 justoneapi 子项，不要覆盖已有的 MCP server 配置。

mcp_servers:
  justoneapi:
    url: "https://mcp.justoneapi.com/mcp"
    headers:
      Authorization: "Bearer ${JUSTONEAPI_TOKEN}"
    tools:
      include:
        - search_endpoints
        - get_endpoint_schema
        - call_endpoint
        - get_account_balance
        - get_usage_summary
        - list_platforms
      resources: false
      prompts: false

环境变量文件中只填写原始 Token，不要添加 Bearer 前缀。上面的工具白名单包含普通客户可以使用的接口检索、调用和账户查询工具，不包含管理员专用的目录刷新工具。

保存配置后，在终端测试连接和工具发现：

hermes mcp test justoneapi

测试通过后，可以运行 hermes chat 启动 Hermes。如果 Hermes 会话已经打开，请在会话中输入 /reload-mcp 重新加载 MCP 配置。然后可以先用一条不产生业务接口调用的提示词确认工具可用：

使用 JustOneAPI 查找小红书笔记评论接口，并告诉我需要哪些参数，暂时不要调用付费接口。

更多配置说明可以查看 Hermes Agent MCP 官方文档。

备用方式：本地 stdio

本地 stdio 适合必须在本机隔离运行 MCP server 的场景。由于公开 npm 包的版本可能晚于远程服务，本文暂不建议把未固定版本的 npx -y justoneapi-mcp 当作与线上服务等价的备用方案。如果必须本地部署，请先在 JustOneAPI MCP GitHub 核对最新发布版本和工具列表；多数用户直接使用上面的 Remote HTTP 方式即可。

可以直接这样问 AI

接入成功后，不需要记工具名，直接用业务语言提问即可。

帮我找小红书笔记评论接口，并告诉我需要哪些参数。

抖音有哪些接口可以获取视频详情？

帮我调用小红书笔记评论接口，笔记 ID 是 xxxxx。

列出微博搜索相关接口，并说明每个接口适合什么场景。

继续获取下一页结果。

帮我查一下 JustOneAPI 余额。

帮我看一下最近的接口调用量和消费情况。

接口返回 code 400，帮我看看可能是哪个参数错了。

接口返回 code 601 或 602，分别是什么意思？

推荐使用流程

• 先让 AI 查找接口，例如“我要获取小红书笔记评论，应该用哪个接口”。
• 再让 AI 查看参数，例如“这个接口需要哪些必填参数，字段分别是什么意思”。
• 提供业务参数后再调用接口，不要让 AI 猜必填参数。
• call_endpoint 可能产生费用；现有 API 权限、价格、限流、余额和 Token 预算仍然生效，调用前可以先让 AI 展示接口与参数。
• 如果返回分页信息，再让 AI 根据返回里的下一页提示继续请求。
• 调试失败时，把返回码和错误信息发给 AI，让它根据接口 schema 和返回码帮你排查。

常见问题

Token 应该放在哪里

OAuth 用户不需要把 API Token 粘贴进客户端，而是在 JustOneAPI 授权页选择要绑定的 Token。只有现有 API Token 兼容方式才使用 Authorization: Bearer your_token 请求头；本地 stdio 使用 JUSTONEAPI_TOKEN 环境变量。不要把真实 Token 提交到项目仓库。

Claude Desktop 可以直接接入吗

Claude.ai、Claude Desktop 和 Claude Code 的 OAuth 接入仍在兼容性测试中，暂不列为正式支持的 OAuth 连接方式。Claude Code 可以按照上面的命令，通过自定义 Authorization 请求头使用现有 API Token。不要把 Token 拼进 URL，也不要把真实 Token 提交到项目仓库。

其他 MCP 客户端怎么接入

如果客户端的 OAuth 注册方式与 JustOneAPI 兼容，可以直接使用远程地址并在浏览器完成授权；如果客户端支持 Streamable HTTP MCP 和自定义请求头，也可以使用本文的 API Token 兼容配置。具体字段名称和账号限制请以对应客户端的官方文档为准。

MCP 会替代 API 文档吗

不会。MCP 更适合让 AI 在工作流里查找和调用接口；API 文档仍然适合人工阅读、确认字段定义和查看完整接口说明。

AI 可以直接调用所有接口吗

AI 通过 OAuth 绑定的 API Token 或你手动配置的现有 API Token 调用接口。实际可调用范围取决于该 Token 当前的账户状态、余额、预算和接口权限。调用前仍建议先让 AI 展示将要使用的接口和参数。

MCP 会截断接口返回吗

不会。接口调用和账户工具会完整返回上游响应，MCP 层不会为了减少内容而截断原始数据。

下一步

ChatGPT 和 Codex 用户可以优先按照上面的 OAuth 步骤连接；Cursor、Hermes Agent 或其他支持自定义请求头的客户端可以继续使用现有 API Token。连接后先让 AI 查找一个你最常用的平台接口，再决定是否发起可能产生费用的调用。需要完整接口说明时，可以同时打开 Just One API 文档；需要查看源码和更新记录时，可以访问 JustOneAPI MCP GitHub。