API reference
MCP tools on the API
The model can call tools on remote MCP servers you name in the request. Vani connects to each server, lists its tools, runs the calls the model makes and feeds the results back, all inside one billed request. This is separate from the Vani MCP server, which lets other assistants use Vani.
- Responses
- tools: [{"type": "mcp", …}]
- Messages
- mcp_servers + mcp_toolset
- Beta headers (Messages)
- mcp-client-2025-11-20, mcp-client-2026-09-15, mcp-client-2025-04-04
- Servers per request
- Up to 5, HTTPS only
On this pageResponses: the mcp tool
Responses: the mcp tool
Add one mcp tool per server. Fields: server_label (required, unique), server_url (required, HTTPS), authorization (sent as the bearer token), headers, server_description, allowed_tools (a list of names, or {"tool_names": [...], "read_only": true}), require_approval (always, never, or {"always"|"never": {"tool_names": [...]}}; default always) and defer_loading. connector_id and tunnel_id are not supported.
- The response contains
mcp_list_tools,mcp_calland, when approval is needed,mcp_approval_requestitems. To answer one, send the whole input again with thatmcp_approval_requestitem followed by anmcp_approval_responseitem (approval_request_id,approve: true|false, optionalreason). Approvals expire after one hour; at most 8 per request. - An approved call runs once: its
mcp_callitem carries theapproval_request_id, and while that item stays in your input the call is not run again. A denied call never runs and has nomcp_callitem; the model is told it was denied. - The API is stateless: send the
mcptool definitions again on every request; earliermcp_list_toolsitems in the input spare a second listing.
Responses request with an MCP server
curl "https://api.vani.ai/v1/responses" \
-H "Authorization: Bearer $VANI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-6-sol",
"store": false,
"input": "Which transports does the MCP spec define?",
"tools": [{
"type": "mcp",
"server_label": "deepwiki",
"server_url": "https://mcp.deepwiki.com/mcp",
"require_approval": "never"
}]
}'Messages: mcp_servers
Send mcp_servers (each {"type": "url", "url", "name", "authorization_token"}) with the anthropic-beta header mcp-client-2025-11-20, and reference every server from tools with one {"type": "mcp_toolset", "mcp_server_name": …}. A toolset may set default_config: {"enabled": false} and per-tool configs to allow only some tools.
mcp-client-2026-09-15also returnsmcp_tool_listingblocks at the start of an answer. Send the answer back as it came: a listing in the history pins that server's tools (only the tools it names are offered) and is not listed again.- The older
mcp-client-2025-04-04is accepted with its own shape: nomcp_toolset; each server may carrytool_configuration: {"enabled", "allowed_tools"}. - The answer contains
mcp_tool_useandmcp_tool_resultblocks in order with the text. Calls run without an approval step.
Messages request with an MCP server
curl "https://api.vani.ai/v1/messages" \
-H "x-api-key: $VANI_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5.5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Which transports does the MCP spec define?"}],
"mcp_servers": [{"type": "url", "url": "https://mcp.deepwiki.com/mcp", "name": "deepwiki"}],
"tools": [{"type": "mcp_toolset", "mcp_server_name": "deepwiki"}]
}'Limits, safety and billing
- Up to 5 servers per request. URLs must be public HTTPS; private networks, localhost and a list of blocked hosts are refused before any connection.
- Tokens and headers you send are used for that request only and never logged or stored.
- Tool results are untrusted text: the model is told so. Every model turn of the loop is billed like any other request; MCP calls themselves are free.
usageis the sum of all model turns, and each turn reads the earlier tool results again. - Chat Completions has no MCP tools: a
tools[]entry of typemcpis refused with 400. Use client-side function tools there, or the Responses or Messages endpoint for MCP servers.
More reference: OpenAI-compatible API · Anthropic-compatible API · Model ids, limits, headers and usage · Images and PDFs on the API · Web search and web fetch tools · Media API: images and videos · Artifacts API · Responses API: scope and limits · Model changes: webhooks, feeds and the changes API · API overview · Docs and quickstart