Skip to content

MCP (Model Context Protocol)

MCP lets an AI app pull in tools and data: files, tickets, databases. Whatever an MCP server returns ends up in the next model call. Point the app's model calls at the gateway and that content is checked by your guardrails before a provider sees it, every call is charged to the right team, and Request logs shows which tools were offered and called.

What it is

MCP connects an AI app (the host: a coding assistant, a chat app, an agent you write) to MCP servers that offer tools and data. Two kinds of traffic are involved, and the gateway carries only one:

flowchart LR
  host["AI app (MCP host)"] -- "model calls, with tool definitions and tool results" --> gw["Vidai gateway"]
  gw --> provider["Model provider"]
  host -- "MCP: list tools, call tools, read resources" --> mcp["MCP servers"]
  • Model calls go from the app to a model. When the app's model address is the gateway, they go through it, with the tools the app offers the model and the results the tools returned.
  • MCP traffic (listing tools, calling them, reading resources) goes straight from the app to each MCP server. It never reaches the gateway, and needs no setting in Vidai.

So you govern MCP through the model calls: the gateway sees every tool definition the model is offered, every tool call it makes and every result sent back to it.

The two settings

The settings belong to the app's model, not to MCP: set the app's model address to the gateway and its key to a Vidai key.

App's model format Base address Key
OpenAI https://<your-gateway>/v1 Your Vidai key (starts vk_)
Anthropic https://<your-gateway> Your Vidai key
Google GenAI https://<your-gateway> Your Vidai key

Apps that let you set these include Claude Code, agent frameworks such as LangChain, the OpenAI Agents SDK, the Claude Agent SDK and Google's ADK, and IDE assistants with a custom OpenAI or Anthropic address. An app that only calls its vendor's own models, with no address to set, can't go through the gateway, MCP or not.

The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.

A minimal call

An agent with the OpenAI Agents SDK and a file-system MCP server, its model calls through the gateway:

import asyncio
from agents import Agent, Runner, set_default_openai_api, set_tracing_disabled
from agents.mcp import MCPServerStdio

set_default_openai_api("chat_completions")  # Chat Completions reaches every provider through the gateway
set_tracing_disabled(True)                  # the SDK's tracing would send your Vidai key to OpenAI

async def main():
    async with MCPServerStdio(
        params={"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]}
    ) as files:
        agent = Agent(name="helper", model="claude-sonnet-4.5", mcp_servers=[files])
        result = await Runner.run(agent, "Which files are in this folder?")
        print(result.final_output)

asyncio.run(main())

Run it with OPENAI_BASE_URL=https://<your-gateway>/v1 and OPENAI_API_KEY=vk_…. The SDK lists the MCP server's tools itself, offers them to the model through the gateway, runs the tool the model chooses against the MCP server, and sends the result back through the gateway. Any approved model works: the gateway translates tools both ways.

Tool calls

Tools from MCP servers are ordinary tools to the model, so they work on every provider the gateway translates to, in the Chat Completions, Messages and Gemini formats. Two things the gateway does for MCP tools:

  • Dotted names. MCP tools are often named like files.read_file; some providers refuse dots in tool names. The gateway renames the tool for those providers (files_read_file) and restores the original name in the answer, so the app sees the name it offered. A provider's own logs show the renamed form.
  • Guardrails on tool results. A tool's result is part of the next model call, so your guardrails check it like any other content, in all three formats: personal data read from a file or ticket can be masked or blocked before the provider sees it. The arguments the model writes for a tool call are not checked.

Reading what the gateway did

In Request logs:

  • The Tool filter under More filters finds calls that offered the model a tool, or called it, by the tool's name.
  • A call that offered tools shows a tools sign and a count such as 1/3 (tools called out of tools offered).
  • Opening a call shows Tools (offered, and called with a tick) and the conversation: each tool the model called with its arguments, and each tool's result.

The app's own MCP traffic isn't in Request logs: the app's or the MCP server's logs have it.

Errors

The gateway's errors arrive in the app's model format, as for any call; match on x-vidai-error-code. Two that MCP setups meet more than most:

Status Gateway code Why
403 content_guardrail_blocked A tool result (a file, a page, a record) held something a guardrail blocks
413 payload_too_large Many tools with long descriptions, or a very large tool result

What goes through the gateway

Part of an MCP setup Through the gateway
The app's model calls, with MCP tools offered and tool results sent back Yes, when the app's model address is the gateway
MCP traffic between the app and MCP servers No: it goes straight to the server
MCP servers a provider connects to for you (a remote MCP tool in OpenAI's Responses API) The call to the model goes through the gateway, to OpenAI and Azure OpenAI models only; the provider talks to the MCP server itself
Anthropic's MCP connector (mcp_servers in a Messages call, with its anthropic-beta header) Only to Anthropic models: the gateway passes the field and the header on unchanged, and the provider talks to the MCP server itself
An app that can't set its model address No

Check it works in a minute

Run the agent above, or ask your MCP-enabled app something that needs a tool. Then in Request logs, open More filters › Tool and type the tool's name: the call that offered it shows within seconds.

Good to know

  • An app sends every tool's definition with every call: dozens of MCP tools add thousands of tokens to each call, and cost. Turn off the MCP servers a task doesn't need.
  • A local model with a small context window may silently cut the start of a long prompt, where the tool definitions sit; raise its context length on the model's server.
  • Some small models mis-call tool names that use hyphens; when that happens, a larger model or tool names with underscores helps.
  • The OpenAI Agents SDK uses the Responses API unless told otherwise; through the gateway that reaches OpenAI and Azure OpenAI models only. set_default_openai_api("chat_completions") opens every provider.