# MCP Server Configuration for Gemini Agents: A Complete API Guide

> Configure MCP servers for Gemini agents efficiently. Learn how to add mcp entries to the tools array for seamless API integration and hidden header injection.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: api-reference
- Published: 2026-06-09

---

**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`](https://github.com/google/skills/blob/main/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.

```bash
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.

```python
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.

```json
{
  "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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/cloud/gemini-agents-api/SKILL.md), with supplementary best practices in [`skills/cloud/gemini-agents-api/references/mcp-usage.md`](https://github.com/google/skills/blob/main/skills/cloud/gemini-agents-api/references/mcp-usage.md) and interaction patterns in [`skills/cloud/gemini-interactions-api/SKILL.md`](https://github.com/google/skills/blob/main/skills/cloud/gemini-interactions-api/SKILL.md).