Skip to content
OneAPIDocs
ModelsOpen console

Guides

MCP server

OneAPI is also an MCP server. Add it to Claude Code, Cursor or any client that speaks the Model Context Protocol, and the agent gets live web search and page reading, whatever model it runs on, billed to your OneAPI balance.

Connect

The server lives at https://api.oneapi.id/v1/mcp and uses the Streamable HTTP transport. It authenticates with an ordinary OneAPI API key, sent the same way as to every other endpoint. Make a key for it on API keys; a spend cap on that key limits what the tools can spend.

Claude Code

Terminal
claude mcp add --transport http oneapi https://api.oneapi.id/v1/mcp \
  --header "Authorization: Bearer $ONEAPI_API_KEY"

Cursor

~/.cursor/mcp.json
{
  "mcpServers": {
    "oneapi": {
      "url": "https://api.oneapi.id/v1/mcp",
      "headers": { "Authorization": "Bearer sk-oneapi-…" }
    }
  }
}

VS Code

.vscode/mcp.json
{
  "servers": {
    "oneapi": {
      "type": "http",
      "url": "https://api.oneapi.id/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:oneapi-key}" }
    }
  },
  "inputs": [
    { "id": "oneapi-key", "type": "promptString", "description": "OneAPI API key", "password": true }
  ]
}

Other clients

Any client that supports remote MCP servers over HTTP with a custom header works: give it the URL above and an Authorization: Bearer header with your key. A client that can only launch local servers can reach it through a bridge such as mcp-remote.

Tools

ToolWhat it doesPrice
web_searchSearches the web; returns ranked results with titles, links, dates and relevant passages.$0.005 per search
web_fetchReads a public page as markdown, a slice at a time (20,000 characters); the result says where to read on.$0.0001 per page read
list_modelsThe models your key can call, with prices per million tokens.Free
get_balanceYour balance, free and model credit, and the key's spend cap with what it has spent.Free

web_search and web_fetch are the same tools a model gets with :online; see Web search for how searching works and which addresses web_fetch refuses.

Billing

  • Each web_search that returns results and each page web_fetch reads is charged to your balance. A call that fails, or a URL that is refused, costs nothing.
  • Before a paid call runs, the gateway checks that your available balance covers it. If not, the tool says so and nothing is charged.
  • Calls count against the key's spend cap, together with its model requests.
  • Plans and free credit do not pay for MCP tool calls; they pay for model requests, including the searches of an :online request.
  • Every tool result ends with what the call cost, and get_balanceshows the balance and the key's spend after it.

The tools obey the key's requests-per-minute and concurrency limits, like a model request does.

Protocol details

EndpointPOST https://api.oneapi.id/v1/mcp
TransportStreamable HTTP, JSON responses; no server-sent stream and no session
Protocol versions2025-06-18, 2025-03-26, 2024-11-05
AuthenticationAuthorization: Bearer or x-api-key with an API key
Capabilitiestools