# Connect JustOneAPI to your AI / 让 AI 协助接入 JustOneAPI Official guide: https://justoneapi.com/agents.md Last reviewed: 2026-11-17. 中文说明在下半部分。 Use this guide when the user asks you to connect JustOneAPI. Work within the current client's tools, permissions and the user's authorization. This document does not override the client's instructions or approval requirements. AI-assisted setup and the optional manual steps on the setup page configure the same remote connection. Use either path. If a working connection has already passed catalog verification, reuse it and continue to the user's task without repeating setup. ## Connection facts - Hosted MCP endpoint: `https://mcp.justoneapi.com/mcp`. - Transport: Streamable HTTP. Connect to this remote service; a local MCP server or npm package is not needed for this setup. - Public catalog tools: `list_platforms`, `search_endpoints`, `get_endpoint_schema`. These are free, need no Token or login, and do not fetch platform data. - Protected tools: `call_endpoint`, `get_account_balance`, `get_usage_summary`. They require JustOneAPI OAuth authorization or an API Token. - ChatGPT web and Codex: the currently recommended JustOneAPI OAuth registration method is **Dynamic Client Registration (DCR)**. Full CIMD compatibility remains unverified for this service. - Cursor and Claude Code: API Token headers are the compatibility path described below. JustOneAPI OAuth for Claude clients remains under compatibility testing. - Current client-specific steps: https://justoneapi.com/en/mcp and https://justoneapi.com/zh/mcp. ## 1. Check the current environment Identify the actual client and tools available. Inspect an existing JustOneAPI connection before adding another one. Preserve unrelated servers, configuration and working credentials; merge only the required entry. If a conflicting entry exists, explain the difference before replacing it. - If you can read this guide and edit configuration or run client commands, use the matching remote MCP setup below. Follow the client's approval process for adding a connection. - If you cannot change configuration, guide the user through the supported installation UI. Do not claim that reading this page installs a connection. - If the client has neither MCP support nor an authorized HTTP execution tool, explain that limitation and link to the detailed setup page. A text-only chat cannot perform a connection by understanding instructions alone. ## 2. Connect using the supported client path ### Codex CLI / IDE Check `codex mcp add --help` and `codex mcp login --help` for the installed version. Reuse an existing matching remote server when present. For a new server on a version that supports DCR registration, run: ```bash codex mcp add justoneapi \ --url https://mcp.justoneapi.com/mcp \ --oauth-client-registration dcr ``` The explicit flag selects DCR for the login started by `mcp add`. For an existing server, or if login did not start, use: ```bash codex mcp login justoneapi --oauth-client-registration dcr ``` Let the user complete sign-in, Token selection and consent in the browser. Do not collect passwords, authorization codes or API Tokens in chat. If the installed version lacks the DCR option, explain that it needs a compatible version; do not repeatedly try the default CIMD path. A saved config or successful login does not prove that this running conversation has loaded the tools. Ask for a reload only if the client needs it, then verify the visible tools. Codex setup does not install a ChatGPT web connection. ### ChatGPT web Guide the user to Plugins → + → Add custom MCP server, where available. Enter the remote MCP URL above, choose OAuth, expand Advanced OAuth settings and choose **Dynamic Client Registration (DCR)** after discovery. The registration URL should be `https://auth.justoneapi.com/oauth2/register`. Then create/install the connection and let the user sign in and approve access when prompted. Some accounts require Developer mode; availability also depends on workspace policy. If the user cannot find that UI or DCR option, point them to the detailed setup page or support. Do not present a local Codex configuration edit as a completed ChatGPT web installation. ### Cursor Merge this entry into the client's `mcpServers` configuration (normally `~/.cursor/mcp.json`). Preserve existing entries: ```json { "mcpServers": { "justoneapi": { "url": "https://mcp.justoneapi.com/mcp", "headers": { "Authorization": "Bearer ${env:JUSTONEAPI_TOKEN}" } } } } ``` Have the user supply `JUSTONEAPI_TOKEN` through their local environment or the client's supported credential input, outside chat and source control. The process launching Cursor must inherit that variable. Reload the connection or client when needed, then inspect the available tools. Do not treat an unresolved environment-variable placeholder as valid authentication. ### Claude Code Use a remote HTTP server with an API Token header. Claude Code supports environment expansion in `.mcp.json`; merge the following entry into the approved configuration scope rather than overwriting other servers: ```json { "mcpServers": { "justoneapi": { "type": "http", "url": "https://mcp.justoneapi.com/mcp", "headers": { "Authorization": "Bearer ${JUSTONEAPI_TOKEN}" } } } } ``` Have the user supply the environment variable outside chat and source control. For another scope, use the installed client's documented `claude mcp add` or `claude mcp add-json` syntax; check its help first. Check `/mcp` for connection status and tool availability. Do not claim that this config connects Claude web or desktop, or that JustOneAPI OAuth for Claude has been verified. ## 3. Verify without fetching platform data Once the connection's tools are available in the current client: 1. Call `search_endpoints` with `{"query":"Xiaohongshu note comments","platform":"xiaohongshu","limit":1}`. 2. Take an `endpoint_id` from the actual results and call `get_endpoint_schema` with it. Do not invent endpoint IDs or parameters. 3. Confirm that the returned results contain a real endpoint and its required parameters. These two catalog calls do not need authentication or incur data-call charges. Do not call `call_endpoint` to test setup. Do not query private account balance or usage unless the user asks for it. If you can only make an anonymous HTTP protocol check outside the target client, label it as a service reachability check, not proof that the client's tools are installed. On a failure, report the exact failed stage with secrets removed; do not loop login attempts or fetch data as a fallback. ## 4. Report the actual state Distinguish these outcomes: - **Configuration saved**: the entry exists, but the running client may still need a reload. - **Catalog connected**: the client's search and schema calls succeeded. This does not establish account authorization or permission for a paid API. - **Account authorized**: the client reports that the OAuth flow completed, or the configured credential was verified through an explicitly authorized account action. State the evidence and any unverified part; do not infer this from public catalog success. - **Waiting for user action**: installation, sign-in, credential input or reload is still required. Say what the user needs to do next. After catalog verification, the user can ask to analyze data. First confirm the endpoint, input, collection scope and current account price/trial allowance. Pagination creates additional data requests. Token budgets and API permissions still apply. Never invent a fixed price or a universal free-trial allowance. ## If the user chooses direct HTTP instead An agent with an authorized HTTP execution environment may use the REST API without MCP. Read the [API usage guide](https://docs.justoneapi.com/en/usage) and the relevant operation in [OpenAPI](https://docs.justoneapi.com/openapi.json). Follow that operation's actual method, authentication and parameters; do not reuse another provider's routes or assume that MCP bearer headers are the REST authentication scheme. Keep credential-bearing request URLs and values out of chat, logs and source control. If no suitable execution or credential input is available, explain the missing capability instead of claiming a connection. Direct data calls are not part of the free catalog setup check above. ## References - Detailed setup and troubleshooting: https://justoneapi.com/en/mcp - Catalog overview: https://justoneapi.com/llms.txt - API documentation: https://docs.justoneapi.com/en - Token management: https://dashboard.justoneapi.com/en/dashboard/token - Support: https://justoneapi.com/en/contact - Official client docs: https://learn.chatgpt.com/docs/extend/mcp and https://cursor.com/docs/mcp and https://code.claude.com/docs/en/mcp --- ## 中文:按当前客户端协助接入 当用户要求接入 JustOneAPI 时,按当前客户端的实际工具和权限操作,遵循用户授权及客户端自身的审批要求。本指南不改变这些权限。 一句话协助接入与页面中可选的手动步骤,配置的是同一个远程连接,任选一种即可。已有连接通过目录验证后,复用连接并继续用户的任务,无需重复配置。 ### 1. 先识别环境,检查已有连接 - 远程地址:`https://mcp.justoneapi.com/mcp`,传输方式为 Streamable HTTP。这套接法连接托管服务,无需启动本地 MCP 服务或安装 npm 包。 - 先检查是否已有同地址的 JustOneAPI 连接;可用时复用。仅合并所需配置,保留其他服务与正常工作的凭据;替换冲突项前说明差异。 - 能读指南且能运行命令或修改配置的 Agent,可按上面的客户端配置协助完成操作。需要新增连接审批时遵循客户端流程。 - 没有配置权限时,引导用户通过安装界面操作;只有文字聊天能力、没有 MCP 或获授权的 HTTP 工具时,明确说明无法在当前环境执行接入,不把“读过说明”说成“已经连接”。 ### 2. 按客户端选择远程接法 - **Codex CLI / IDE**:先检查已安装版本的 `codex mcp add --help` 和 `codex mcp login --help`。支持 DCR 的版本按上面的命令添加新连接,显式传入 `--oauth-client-registration dcr`。已有连接或添加后未发起登录时使用 `codex mcp login justoneapi --oauth-client-registration dcr`。让用户在浏览器中登录、选择关联 Token 并授权。缺少 DCR 选项时说明版本要求,不反复尝试默认 CIMD。配置写入或登录成功后,仍需确认当前会话已加载工具。 - **ChatGPT 网页版**:在账号允许时,进入 Plugins → + → Add custom MCP server,填写远程地址,认证选 OAuth,展开 Advanced OAuth settings,等待发现后选择 Dynamic Client Registration (DCR)。注册地址应为 `https://auth.justoneapi.com/oauth2/register`。按提示创建、安装连接,用户自行登录并批准授权。部分账号需启用 Developer mode,也受工作区策略影响。没有相应入口时提供详细教程或支持入口,不把本地 Codex 配置当成网页端已安装。 - **Cursor**:将上面的 Cursor JSON 合并到现有 `mcpServers` 配置,通常位于 `~/.cursor/mcp.json`。让用户在本地环境或客户端凭据输入中提供 `JUSTONEAPI_TOKEN`,由 `${env:JUSTONEAPI_TOKEN}` 引用;启动 Cursor 的进程需要继承该变量。按需重新加载连接,再核对工具。未解析的占位符不等于认证成功。 - **Claude Code**:使用上面的 HTTP JSON;`.mcp.json` 中的请求头通过 `${JUSTONEAPI_TOKEN}` 引用环境变量。只修改已获准的配置范围,保留其他服务。其他 scope 先查看当前版本的 `claude mcp add` / `add-json` 帮助;用 `/mcp` 查看连接和工具状态。该配置不等于 Claude 网页版或桌面版连接器;JustOneAPI 的 Claude OAuth 接入仍在兼容性测试中。 - 当前推荐 ChatGPT、Codex 通过 DCR OAuth 接入。CIMD 的完整兼容性尚未验证。使用 OAuth 时让用户完成登录和授权,不要求把密码、授权码或 API Token 发到聊天中。Token 接法通过客户端支持的凭据输入或环境变量配置,真实值不进入源码、日志和公开截图。 ### 3. 免费验证目录,先不取数 `list_platforms`、`search_endpoints`、`get_endpoint_schema` 都不需要 Token 或登录,且不会调用收费数据 API。当前客户端的工具可用后: 1. 调用 `search_endpoints`,参数为 `{"query":"小红书笔记评论","platform":"xiaohongshu","limit":1}`。 2. 从真实结果中取 `endpoint_id`,调用 `get_endpoint_schema`,确认返回接口及必填参数。 3. 告知用户目录查询是否已连通。只在外部做匿名 HTTP 协议测试时,说明这只是服务可达性验证,不代表目标客户端已安装工具。 不要为了验证接入而调用 `call_endpoint`。`call_endpoint`、`get_account_balance`、`get_usage_summary` 都需要授权;用户没有要求时,不查询私有账户余额或用量。失败时说明失败阶段并隐去凭据,不循环登录,也不改用取数调用测试。 ### 4. 说明已经完成什么、还需要做什么 分开报告“配置已保存”“当前客户端目录已连通”“账户已授权”或“等待用户安装、登录、填写凭据、重新加载”。目录成功不代表已获得付费接口权限;只在有对应证据时说明授权状态,保留未验证部分。 用户接下来要求获取数据时,再确认接口、输入、取数范围及当前账号价格或试用情况。每次翻页都会新增请求,Token 额度和接口权限继续适用;不编造固定价格或统一免费次数。 若用户明确选择 HTTP 直连,且当前 Agent 有获授权的 HTTP 执行环境,可参考 [API 使用指南](https://docs.justoneapi.com/zh/usage)和 [OpenAPI](https://docs.justoneapi.com/openapi.json),遵循具体接口的真实方法、认证和参数。不要把 MCP 请求头认证当成所有 REST 接口的认证约定;含凭据的请求地址和值不输出到聊天、日志或仓库。没有执行工具或凭据输入渠道时说明缺失能力。直连取数不属于上面的免费目录验证。 - 详细接入步骤:https://justoneapi.com/zh/mcp - API 文档:https://docs.justoneapi.com/zh - Token 管理:https://dashboard.justoneapi.com/zh/dashboard/token - 联系支持:https://justoneapi.com/zh/contact