返回教程列表
教程2026年6月28日6 分钟阅读

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

学习如何在 Claude Code、Codex、Cursor、Hermes Agent 等客户端中接入 JustOneAPI MCP Server，让 AI 助手帮你查找接口、查看参数并调用 API。

MCP 是什么

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

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

JustOneAPI MCP 能解决什么问题

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

准备 JustOneAPI Token

使用 MCP 前，你需要准备一个 JustOneAPI Token。登录 JustOneAPI Dashboard 后，在账户或 API Token 相关页面复制你的 token。

Token 是敏感信息。不要把真实 token 写进公开仓库、公开截图或发给不可信的人。配置示例里的 your_token 需要替换成你自己的 token。

支持哪些客户端

JustOneAPI MCP 推荐使用 Streamable HTTP 远程接入。目前可以直接按照本文配置的常用客户端包括：

  • Claude Code
  • Codex CLI、Codex App 和 Codex IDE 扩展
  • Cursor
  • Hermes Agent
  • 其他支持远程 HTTP MCP server 和自定义请求头的客户端

不同客户端的配置文件和命令不完全相同，但使用的是同一个 MCP 地址和认证方式。

通用连接信息

  • MCP 地址：https://mcp.justoneapi.com/mcp
  • 请求头：Authorization: Bearer your_token

如果你的客户端采用常见的 mcpServers JSON 结构，可以参考下面的写法：

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

配置完成后，重启或刷新你的 MCP 客户端。客户端必须同时支持远程 HTTP MCP server 和自定义 Authorization 请求头，才能使用这种方式连接。

按客户端接入

Claude Code

Claude Code 可以通过命令直接添加远程 HTTP MCP server。下面使用 user scope，让配置在你的个人项目中可用，同时避免把包含 Token 的配置提交到项目仓库。

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

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

bash
claude mcp get justoneapi

启动 Claude Code 后，还可以输入 /mcp 确认 JustOneAPI 已连接。更多配置说明请查看 Claude Code MCP 官方文档。

Codex

Codex 支持通过环境变量提供 Bearer Token。先在启动 Codex 的终端中设置 Token，再添加远程 MCP server：

bash
export JUSTONEAPI_TOKEN="your_token"

codex mcp add justoneapi \
  --url https://mcp.justoneapi.com/mcp \
  --bearer-token-env-var JUSTONEAPI_TOKEN

运行下面的命令确认配置已经写入：

bash
codex mcp get justoneapi

Codex CLI、Codex App 和 Codex IDE 扩展会读取同一份 ~/.codex/config.toml 配置。使用时要确保启动 Codex 的进程能够读取 JUSTONEAPI_TOKEN 环境变量，然后重新启动 Codex。更多配置说明请查看 Codex MCP 官方文档。

Cursor

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

bash
export JUSTONEAPI_TOKEN="your_token"

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

json
{
  "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：

dotenv
JUSTONEAPI_TOKEN=your_token

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

yaml
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 前缀。上面的工具白名单包含普通客户可以使用的接口检索、调用和账户查询工具，不包含管理员专用的目录刷新工具。

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

bash
hermes mcp test justoneapi

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

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

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

备用方式：本地 stdio

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

可以直接这样问 AI

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

text
帮我找小红书笔记评论接口，并告诉我需要哪些参数。
text
抖音有哪些接口可以获取视频详情？
text
帮我调用小红书笔记评论接口，笔记 ID 是 xxxxx。
text
列出微博搜索相关接口，并说明每个接口适合什么场景。
text
继续获取下一页结果。
text
帮我查一下 JustOneAPI 余额。
text
帮我看一下最近的接口调用量和消费情况。
text
接口返回 code 400，帮我看看可能是哪个参数错了。
text
接口返回 code 601 或 602，分别是什么意思？

推荐使用流程

  • 先让 AI 查找接口，例如“我要获取小红书笔记评论，应该用哪个接口”。
  • 再让 AI 查看参数，例如“这个接口需要哪些必填参数，字段分别是什么意思”。
  • 提供业务参数后再调用接口，不要让 AI 猜必填参数。
  • 如果返回分页信息，再让 AI 根据返回里的下一页提示继续请求。
  • 调试失败时，把返回码和错误信息发给 AI，让它根据接口 schema 和返回码帮你排查。

常见问题

Token 应该放在哪里

远程 HTTP 请求最终都使用 Authorization: Bearer your_token 请求头。优先按照客户端支持的方式从环境变量读取 Token，不要把真实 Token 提交到项目仓库。本地 stdio 使用 JUSTONEAPI_TOKEN 环境变量。

Claude Desktop 可以直接接入吗

这取决于你的 Claude 账号或组织是否已获得仍在 beta 阶段的 Request headers 功能。如果 Add custom connector 页面提供该选项，请把 Header name 填为 Authorization、Header value 填为 Bearer your_token，并开启 Required；如果没有这个选项，就无法为当前 JustOneAPI 远程地址配置静态 Bearer Token。Team 和 Enterprise 组织只能由 Owner 添加连接器，而且静态请求头会作为组织共享凭证发送，这意味着所有成员将共用同一个 JustOneAPI Token；需要每位成员独立计费或授权时，不要使用这种配置。不要把 Token 拼进 URL，也可以改用本文列出的 Claude Code、Codex、Cursor 或 Hermes Agent。详情请查看 Claude Request headers 官方说明。

其他 MCP 客户端怎么接入

只要客户端支持 Streamable HTTP MCP 和自定义请求头，就可以使用本文的通用 MCP 地址与 Authorization 请求头。配置字段名称请以对应客户端的官方文档为准。

MCP 会替代 API 文档吗

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

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

AI 需要通过 JustOneAPI Token 调用接口，实际可调用范围取决于你的账户、余额和接口权限。调用前仍建议先让 AI 展示将要使用的接口和参数。

下一步

如果你已经有 JustOneAPI Token，可以从 Claude Code、Codex、Cursor 或 Hermes Agent 中选择正在使用的客户端，按照上面的步骤接入，然后让 AI 查找一个你最常用的平台接口。需要完整接口说明时，可以同时打开 Just One API 文档；需要查看源码和更新记录时，可以访问 JustOneAPI MCP GitHub。

继续使用 Just One API

登录 Dashboard 获取 Token，查看完整 API 文档，或打开 MCP GitHub 项目了解最新配置。

登录 Dashboard查看 API 文档GitHub