Gemini — Model Context Protocol (MCP): SDK-side support and server-side mcpServers
Status: DOCUMENTED (SDK-side feature; not exercised live 2026-09-18)
Sources:
- https://ai.google.dev/gemini-api/docs/generate-content/function-calling#model-context-protocol-mcp · https://ai.google.dev/gemini-api/docs/function-calling#remote-mcp-model-context-protocol (Interactions)
- https://github.com/googleapis/python-genai (README "Model Context Protocol (MCP) support (experimental)") · https://github.com/googleapis/js-genai (README,
mcpToTool) - https://ai.google.dev/api/generate-content (#Tool
mcpServers[], #McpServer, #StreamableHttpTransport) · https://ai.google.dev/gemini-api/docs/deep-research (toolmcp_server) - SDK types
google-genai2.24 (Tool.mcp_servers,McpServer,StreamableHttpTransport)
Last verified: 2026-09-18 (docs only)
1. Two different things
| SDK-side MCP (documented for generateContent) | Server-side MCP (tools[].mcpServers) |
|
|---|---|---|
| Where the MCP client runs | in your process (google-genai / @google/genai) | on Google's side (schema only) |
| Wire format | ordinary functionDeclarations / functionCall / functionResponse |
tools[].mcpServers[]{name, streamableHttpTransport{url, headers, timeout, sseReadTimeout, terminateOnClose}} |
| Docs | generateContent function-calling guide, SDK READMEs | REST reference + discovery only; Python README shows Tool.mcp_servers only for the "Gemini Enterprise Agent Platform"; SDK type says "not supported in Vertex AI" |
| Status | DOCUMENTED, experimental (BETA) | DOCUMENTED, DOCUMENTATION_INCOMPLETE, UNVERIFIED on the Gemini Developer API |
| Interactions API twin | — | documented: tools:[{"type":"mcp_server","name","url","headers","allowed_tools"}]; Streamable HTTP only (no SSE); names without -; also a Deep Research agent tool |
Whether POST /v1beta/models/{model}:generateContent or the Live API honours tools[].mcpServers is not documented → UNVERIFIED (parent agent may probe with a dummy URL and record the error).
2. SDK-side automatic MCP tool calling
| Step | Python google-genai |
JS @google/genai |
|---|---|---|
| Install | pip install mcp (plus google-genai) |
npm i @modelcontextprotocol/sdk |
| Connect | stdio_client(StdioServerParameters(...)) → ClientSession; await session.initialize() |
new Client(...); await client.connect(new StdioClientTransport(...)) |
| Pass as tool | config=GenerateContentConfig(tools=[session]) |
config: { tools: [mcpToTool(client)] } |
| Loop | SDK lists MCP tools → declarations; on functionCall it calls the MCP tool and re-sends until no calls remain (automatic_function_calling.maximum_remote_calls default 10) |
same (automaticFunctionCalling.maximumRemoteCalls) |
| Manual mode | automatic_function_calling=AutomaticFunctionCallingConfig(disable=True) → you get functionCall parts |
automaticFunctionCalling: { disable: true } |
| Async | client.aio.models.generate_content |
promises |
Limitations (guide): experimental; tools only (no MCP resources/prompts); Python and JS/TS only; breaking changes possible; Live API has no automatic tool handling; README: AFC moves from Models.generate_content to Chats in the next major version. Manual integration (list tools → build declarations → call server yourself) always works.
3. Examples
python
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai
client = genai.Client() # GEMINI_API_KEY
async def main():
params = StdioServerParameters(command="npx", args=["-y", "@philschmid/weather-mcp"])
async with stdio_client(params) as (r, w):
async with ClientSession(r, w) as session:
await session.initialize()
resp = await client.aio.models.generate_content(model="gemini-3.5-flash-lite",
contents="Weather in London today?", config=genai.types.GenerateContentConfig(tools=[session]))
print(resp.text)
asyncio.run(main())ts
import { GoogleGenAI, mcpToTool } from '@google/genai';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const mcp = new Client({ name: 'demo', version: '1.0.0' });
await mcp.connect(new StdioClientTransport({ command: 'npx', args: ['-y', '@philschmid/weather-mcp'] }));
const ai = new GoogleGenAI({});
const r = await ai.models.generateContent({ model: 'gemini-3.5-flash-lite', contents: 'Weather in London today?',
config: { tools: [mcpToTool(mcp)] } });
console.log(r.text); await mcp.close();bash
# Interactions API (documented server-side MCP)
curl -s "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
-d '{"model":"gemini-3.8-flash","input":"Check the weather in San Francisco.",
"tools":[{"type":"mcp_server","name":"weather","url":"https://gemini-api-demos.uc.r.appspot.com/mcp"}]}'
# generateContent shape from the REST reference (UNVERIFIED):
# "tools":[{"mcpServers":[{"name":"weather","streamableHttpTransport":{"url":"https://…/mcp"}}]}]Live verification (2026-09-18)
Not exercised live (SDK-side feature; tools[].mcpServers server-side variant is undocumented outside the REST reference). No MCP server was available in the sandbox; the automatic-function-calling loop that the SDK MCP integration relies on is the same one verified in examples/shared/tool-loop/gemini_tool_loop.py.