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
claude mcp add --transport http oneapi https://api.oneapi.id/v1/mcp \
--header "Authorization: Bearer $ONEAPI_API_KEY"Cursor
{
"mcpServers": {
"oneapi": {
"url": "https://api.oneapi.id/v1/mcp",
"headers": { "Authorization": "Bearer sk-oneapi-…" }
}
}
}VS Code
{
"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
| Tool | What it does | Price |
|---|---|---|
web_search | Searches the web; returns ranked results with titles, links, dates and relevant passages. | $0.005 per search |
web_fetch | Reads 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_models | The models your key can call, with prices per million tokens. | Free |
get_balance | Your 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_searchthat returns results and each pageweb_fetchreads 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
:onlinerequest. - 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
| Endpoint | POST https://api.oneapi.id/v1/mcp |
| Transport | Streamable HTTP, JSON responses; no server-sent stream and no session |
| Protocol versions | 2025-06-18, 2025-03-26, 2024-11-05 |
| Authentication | Authorization: Bearer or x-api-key with an API key |
| Capabilities | tools |