Skip to content

New: DeepSeek V4.1 Flash Derisked. In chat and on the API.

See modelsWhat's newReport a bug
Open chat
API reference

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_call and, when approval is needed, mcp_approval_request items. To answer one, send the whole input again with that mcp_approval_request item followed by an mcp_approval_response item (approval_request_id, approve: true|false, optional reason). Approvals expire after one hour; at most 8 per request.
  • An approved call runs once: its mcp_call item carries the approval_request_id, and while that item stays in your input the call is not run again. A denied call never runs and has no mcp_call item; the model is told it was denied.
  • The API is stateless: send the mcp tool definitions again on every request; earlier mcp_list_tools items in the input spare a second listing.
Shell

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-15 also returns mcp_tool_listing blocks 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-04 is accepted with its own shape: no mcp_toolset; each server may carry tool_configuration: {"enabled", "allowed_tools"}.
  • The answer contains mcp_tool_use and mcp_tool_result blocks in order with the text. Calls run without an approval step.
Shell

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. usage is 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 type mcp is 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