JustOneAPI MCP Server Tutorial: Let AI Assistants Find and Call Data APIs

What MCP is

MCP stands for Model Context Protocol. It gives AI clients a standard way to connect to external tools, data sources, and APIs. For developers, the practical value is simple: your AI assistant can do real work through a tool protocol instead of only describing what to do.

JustOneAPI MCP Server exposes the Just One API endpoint catalog, parameter schemas, and API calling workflow to MCP-compatible clients. After connecting it, you can ask ChatGPT, Codex, Cursor, Hermes Agent, or another compatible client to find the right endpoint, inspect required parameters, and call an API after you provide the required values.

What JustOneAPI MCP helps with

• You do not need to browse every API document manually. The assistant can search endpoint candidates from a natural language request.
• You do not need to guess parameter names. The assistant can inspect the endpoint schema before explaining required parameters, enum values, and calling rules.
• You do not need to write every request by hand. The assistant can call the selected endpoint after you authorize access and provide the business parameters.
• You can continue paginated results by asking the assistant to follow the next-page hint from the previous response.
• You can check account balance, recent usage, and spending during debugging.
• You can ask the assistant to interpret common response codes and parameter errors.

Choose an authentication method

ChatGPT and Codex should use OAuth. After you configure https://mcp.justoneapi.com/mcp, the client prompts you to open the JustOneAPI authorization page during connection or when you first invoke a protected tool. Sign in, select the API Token to link, and approve access. Account Owners can select an existing Token or create a dedicated one; Token Members can only use the Token assigned to them. OAuth does not require you to paste an API Token into the client, and no additional JustOneAPI feature flag is required.

Clients without MCP OAuth can continue using an existing API Token through the Authorization: Bearer your_token header. Only this compatibility method and local stdio require you to configure a Token manually. Treat every Token as sensitive: never commit one to a public repository, include it in a public screenshot, or share it with an untrusted party.

Supported clients

JustOneAPI MCP recommends a remote connection over Streamable HTTP. This tutorial covers the following setup paths:

• ChatGPT custom MCP connections with OAuth.
• Codex CLI and the Codex IDE extension with OAuth.
• Cursor and Hermes Agent with the existing API Token compatibility method.
• Other remote HTTP MCP clients with custom request headers through the existing API Token compatibility method.
• OAuth for Claude.ai, Claude Desktop, and Claude Code remains under compatibility testing; Claude Code can continue using an existing API Token header.

Every remote client uses the same MCP URL, but authentication depends on its OAuth registration support, account or workspace policy, and support for custom headers. The tutorial only lists verified OAuth paths as recommended connections.

Connection details

• MCP URL: https://mcp.justoneapi.com/mcp
• Recommended authentication: OAuth through the JustOneAPI authorization page.
• Compatibility authentication: Authorization: Bearer your_token.

If your client does not support OAuth but does support the common mcpServers JSON structure and custom headers, use the following compatibility configuration as a reference:

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

After saving the configuration, restart or refresh your MCP client. This JSON example is only for the existing API Token compatibility method; do not add a static Authorization header to an OAuth connection.

Connect by client

ChatGPT web

You can currently add and test a custom MCP connection through ChatGPT Developer mode:

• Open Settings → Security and login and enable Developer mode.
• Open ChatGPT Plugins and select + to create a connection.
• Enter a name and description, then set the Server URL to https://mcp.justoneapi.com/mcp.
• Choose OAuth for Authentication. Do not enter a static API Token or Authorization header.
• Create the connection. During connection or when you first invoke a protected tool, follow the prompt to sign in to JustOneAPI, select the API Token to link, and approve access.

Developer mode availability can depend on the ChatGPT account and workspace policy. OAuth is already enabled in the JustOneAPI production environment and requires no additional setup. See the official OpenAI connection testing guide for the current ChatGPT entry points.

Codex

OAuth is the recommended setup for Codex. Add the remote MCP server, then explicitly use the verified DCR registration path for login:

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

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

When your browser opens the JustOneAPI authorization page, sign in, select the API Token to link, and approve access. Then confirm the saved configuration:

codex mcp get justoneapi

The ChatGPT desktop app, Codex CLI, and Codex IDE extension share MCP configuration on the same Codex host. For more details, see the official OpenAI MCP documentation.

Claude Code with an API Token

OAuth for Claude.ai, Claude Desktop, and Claude Code remains under compatibility testing and is not yet offered as a generally supported OAuth connection. Claude Code can use an existing API Token through a custom Authorization header:

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

Check the saved configuration with:

claude mcp get justoneapi

After starting Claude Code, enter /mcp to confirm that JustOneAPI is connected. Never commit the real Token to a project configuration or repository. For more details, see the official Claude Code MCP documentation.

Cursor

First, set an environment variable for the process that launches Cursor:

export JUSTONEAPI_TOKEN="your_token"

Then add the following configuration to the global file at ~/.cursor/mcp.json. If the file already contains mcpServers, merge only the justoneapi entry.

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

Restart Cursor, open Customize in the sidebar, and confirm that the JustOneAPI MCP server is enabled and its tools are visible. Cursor must be able to read the environment variable above; if you set it in a terminal, launch Cursor from that same terminal. For more details, see the official Cursor MCP documentation.

Hermes Agent

Hermes Agent supports remote HTTP MCP servers natively. To keep your token out of the main configuration file, first save your JustOneAPI token in Hermes's default environment file at ~/.hermes/.env:

JUSTONEAPI_TOKEN=your_token

Then add the following entry to ~/.hermes/config.yaml. If the file already contains mcp_servers, merge only the justoneapi entry instead of replacing your existing MCP server configuration.

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

Put only the raw token in the environment file; do not add the Bearer prefix there. The allowlist exposes the standard endpoint discovery, API calling, and account tools while leaving the admin-only catalog refresh tool unavailable.

After saving the configuration, test the connection and tool discovery from your terminal:

hermes mcp test justoneapi

Once the test passes, run hermes chat to start Hermes. If a Hermes session is already open, enter /reload-mcp inside the session to reload the MCP configuration. You can then start with a prompt that only checks endpoint discovery and does not make a paid API call:

Use JustOneAPI to find the Xiaohongshu note comments endpoint and tell me which parameters it requires. Do not call a paid API yet.

For more configuration details, see the official Hermes Agent MCP documentation.

Alternative setup: local stdio

Local stdio is useful when the MCP server must run in isolation on your own machine. Because the public npm package can lag behind the hosted service, this tutorial does not recommend treating an unpinned npx -y justoneapi-mcp installation as an equivalent fallback. If you require a local deployment, first check the latest release and tool list on JustOneAPI MCP GitHub. Most users should use the Remote HTTP setup above.

Prompts you can use

After the connection works, you do not need to remember tool names. Ask in normal business language.

Find the Xiaohongshu note comments API and tell me which parameters are required.

Which Douyin APIs can get video details?

Call the Xiaohongshu note comments API with this note ID: xxxxx.

List the Weibo search-related APIs and explain when to use each one.

Continue to the next page of results.

Check my JustOneAPI balance.

Show my recent API usage and spending.

The API returned code 400. Help me check which parameter might be wrong.

The API returned code 601 or 602. What does it mean?

Recommended workflow

• First ask the assistant to find an endpoint, such as “Which API should I use to get Xiaohongshu note comments?”
• Then ask it to inspect parameters, such as “Which fields are required and what does each field mean?”
• Provide business parameters before calling the endpoint. Do not ask the assistant to guess required values.
• call_endpoint may incur charges. Existing API permissions, pricing, rate limits, balance checks, and Token budgets still apply, so you can ask the assistant to show the endpoint and parameters before the call.
• If the response includes pagination metadata, ask the assistant to continue with the next-page hint.
• When a call fails, share the response code and error message so the assistant can compare them with the endpoint schema and common return codes.

FAQ

Where should I put the token?

OAuth users do not paste an API Token into the client; they select the Token to link on the JustOneAPI authorization page. Only the existing API Token compatibility method uses the Authorization: Bearer your_token header. Local stdio uses the JUSTONEAPI_TOKEN environment variable. Never commit a real Token to a project repository.

Can I connect Claude Desktop directly?

OAuth for Claude.ai, Claude Desktop, and Claude Code remains under compatibility testing and is not yet offered as a generally supported OAuth connection. Claude Code can use an existing API Token through the custom Authorization header command shown above. Never put the Token in the URL or commit it to a project repository.

How do I connect another MCP client?

If the client's OAuth registration method is compatible with JustOneAPI, it can use the remote URL and complete authorization in the browser. A client with Streamable HTTP MCP and custom request headers can instead use the API Token compatibility configuration. Follow that client's official documentation for exact fields and account restrictions.

Does MCP replace API documentation?

No. MCP is best for letting AI assistants discover and call APIs inside a workflow. API documentation is still the right place for humans to read complete field definitions and endpoint details.

Can the assistant call every API directly?

The assistant calls APIs through the API Token linked during OAuth or the existing API Token you configured manually. Actual access depends on that Token's current account status, balance, budget, and endpoint permissions. Before making a call, it is still a good idea to ask the assistant to show the endpoint and parameters it plans to use.

Does MCP truncate API responses?

No. API and account tools return the complete upstream payload. The MCP layer does not shorten or truncate the original response to reduce its size.

Next steps

ChatGPT and Codex users should start with the OAuth steps above. Cursor, Hermes Agent, and other clients with custom header support can continue using an existing API Token. After connecting, ask the assistant to find an endpoint for a platform you use often before deciding whether to make a billable call. For complete endpoint details, keep the Just One API Docs open. For source code and release updates, visit JustOneAPI MCP GitHub.