MCP Server Configuration for Gemini Agents: A Complete API Guide

You configure MCP servers for Gemini agents by adding "type": "mcp" entries to the tools array in the agent creation payload, where optional headers are injected server-side and kept hidden from the model.

The google/skills repository documents how the Gemini Enterprise Agent Platform connects agents to external data sources through the Model Context Protocol. Understanding MCP server configuration for Gemini agents enables you to register remote HTTPS tools at creation time and override them dynamically during live interactions.

How MCP Tool Registration Works on the Gemini Platform

Control Plane and Data Plane Separation

The Gemini Enterprise Agent Platform separates control-plane operations from data-plane interactions. You create and update agents through the control plane at aiplatform.googleapis.com/v1beta1, while the data plane handles live model interactions via interactions.create.

Tool Registration and Execution Flow

According to skills/cloud/gemini-agents-api/SKILL.md, adding an object with "type": "mcp" to the tools array registers a remote tool. When the model decides to invoke the tool, the platform resolves the name, injects the configured headers, executes the HTTPS call server-side, and returns the structured response to the model.

Static MCP Server Configuration for Gemini Agents at Agent Creation

To attach an MCP server permanently to an agent, send a POST request to the agents endpoint. The tools array accepts an MCP entry containing type, name, url, and an optional headers map.

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-mcp-enabled-agent",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a helpful assistant with access to a private data store.",
    "tools": [
      { "type": "code_execution" },
      { "type": "mcp",
        "name": "private-data-mcp",
        "url": "https://mcp.mycompany.com/v1/query",
        "headers": {
          "Authorization": "Bearer MY_MCP_TOKEN"
        }
      }
    ],
    "base_environment": {
      "type": "remote",
      "sources": [{ "type": "gcs", "source": "gs://my-bucket/skills", "target": "/.agent/skills" }]
    }
  }'

The platform stores this configuration and routes any matching tool calls to the specified URL.

Security Guarantees for MCP Headers

The headers field is whitelisted exclusively for the target url. The platform strips these values from all model-visible context and injects them only into the outbound HTTPS request. This server-side execution preserves the confidentiality of API keys and bearer tokens.

Dynamic MCP Server Configuration for Gemini Agents During Interactions

You can supersede the static MCP configuration without recreating the agent by passing a tool object with "type": "mcp_server" in the tools array of an interaction request. This pattern supports staging environments and multi-tenant deployments.

response = client.interactions.create(
    agent="projects/your-project-id/locations/global/agents/my-mcp-enabled-agent",
    input="Give me the latest sales figures for Q2.",
    tools=[
        {
            "type": "mcp_server",
            "name": "private-data-mcp",
            "url": "https://staging-mcp.mycompany.com/v1/query",
            "headers": {"Authorization": "Bearer STAGING_TOKEN"}
        }
    ]
)

The runtime payload overrides the static agent definition for that conversation only.

MCP Request Flow and Execution Model

When the model elects to use the tool, it emits a structured request. The platform translates this into the actual HTTPS call.

{
  "tool": {
    "type": "mcp",
    "name": "private-data-mcp",
    "input": { "sql": "SELECT revenue FROM sales WHERE quarter='Q2'" }
  }
}

The platform forwards the input to https://mcp.mycompany.com/v1/query alongside the configured headers, then returns the JSON result as a tool response.

Key Source Files in google/skills

• skills/cloud/gemini-agents-api/SKILL.md — Full Managed Agents API documentation and MCP configuration reference.
• skills/cloud/gemini-agents-api/references/mcp-usage.md — Best practices and additional usage notes for MCP servers.
• skills/cloud/gemini-interactions-api/SKILL.md — Interaction-plane API reference demonstrating tools in interactions.create.

Summary

• Add "type": "mcp" objects to the tools array when creating an agent via the control plane.
• Supply url and optional headers; the platform keeps headers private and never exposes them to the model.
• Override static configurations per-conversation by passing "type": "mcp_server" in the tools array of an interaction request.
• All execution happens server-side, ensuring credentials remain confidential throughout the request lifecycle.

Frequently Asked Questions

Where is the MCP configuration defined in the agent payload?

The MCP configuration lives inside the tools array of the agent creation payload sent to https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents. Each entry uses "type": "mcp" and specifies name, url, and optional headers.

Are MCP headers visible to the Gemini model?

No. The platform whitelists headers for the target URL only and strips them from model-visible context. They are injected server-side exclusively for the outbound MCP HTTPS call.

Can I change the MCP server URL without recreating the agent?

Yes. At runtime, pass a tool object with "type": "mcp_server" in the tools array of an interactions.create request. This dynamic override supersedes the static agent configuration for that specific conversation.

What files in the google/skills repository document MCP usage?

The primary documentation lives in skills/cloud/gemini-agents-api/SKILL.md, with supplementary best practices in skills/cloud/gemini-agents-api/references/mcp-usage.md and interaction patterns in skills/cloud/gemini-interactions-api/SKILL.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}