How MCP Server Plugins Work with Google Agent Skills: Integration Guide

MCP server plugins declare external Model Context Protocol endpoints in .mcp.json files, which the Google Agent runtime automatically registers and exposes as callable tools to skills, with automatic fallback to REST APIs when MCP servers are unavailable.

Google Agent Skills in the google/skills repository use a manifest-based architecture where MCP server plugins bridge external tools to agent capabilities. When a skill requires access to external knowledge sources or utilities, it declares an MCP server through a dedicated plugin file rather than hardcoding endpoint logic. This separation allows the Agent runtime to handle connection management, authentication, and tool discovery dynamically.

Understanding the MCP Plugin Architecture

The integration begins with a declarative configuration that tells the Agent runtime where to find and how to connect to MCP-compatible services.

The Plugin Declaration File (.mcp.json)

Each MCP server plugin contains a JSON configuration file that conforms to the MCP schema standard. In plugins/cloud/google-cloud-developer/.mcp.json, the Developer Knowledge MCP server is declared with its transport type and endpoint:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "developer-knowledge": {
      "type": "streamable-http",
      "url": "https://developerknowledge.googleapis.com/mcp"
    }
  }
}

This configuration maps the logical server name developer-knowledge to the physical endpoint https://developerknowledge.googleapis.com/mcp using the streamable-http transport protocol. The $schema field ensures validation against the official MCP plugin specification.

How the Agent Runtime Registers MCP Servers

When the Agent loads a skill, it performs a three-stage registration process that transforms static configuration into runtime-callable tools.

Server Registration – The runtime reads the plugin's mcpServers block and adds the server to its internal MCP registry. This registry maintains the mapping between logical names and concrete connection details, including authentication headers and transport configurations.

Tool Exposure – Once registered, the MCP server advertises its available tools (such as search_documents, answer_query, and get_documents). The Agent automatically injects these tools into the skill's tool set without requiring additional wiring or import statements in the skill code.

Lifecycle Management – The runtime handles connection pooling, health checks, and reconnection logic for declared servers, isolating skill developers from transport-layer concerns.

Using MCP Tools in Skill Manifests

Skills declare their intent to use MCP tools within their SKILL.md manifests, specifying both the preferred MCP workflow and fallback mechanisms.

Declaring Tool Usage in SKILL.md

The skills/developers/retrieving-developer-knowledge/SKILL.md manifest defines the tool selection hierarchy:

## Tool Selection & Usage

### 1. Developer Knowledge MCP Tools (Preferred)

- `answer_query(query="...")` – conceptual guides, architecture overviews.
- `search_documents(query="...", page_size=5)` – CLI flag lookup, IAM permission names.
- `get_documents(names=["documents/..."])` – fetch full documentation pages.

This manifest structure allows the Agent to understand which operations the skill can perform when the MCP server is available. The preferred-first pattern prioritizes MCP tools over direct REST API calls.

Available MCP Tool Methods

The Developer Knowledge MCP server exposes three primary tools that skills can invoke:

• answer_query – Returns conceptual explanations and architectural guidance
• search_documents – Performs semantic search across documentation with configurable result limits
• get_documents – Retrieves full document content by specific resource names

When the runtime executes the skill, it translates these logical tool calls into MCP protocol messages sent to the registered server endpoint.

Implementation Examples

Practical integration requires handling both the success case (MCP available) and the degradation case (MCP unavailable).

Python Client Integration

Skills implemented in Python can access registered MCP servers through the MCPClient class, which resolves server configurations automatically from the plugin registry:

from google.mcp import MCPClient

# The client automatically reads the registered MCP server from the runtime.

client = MCPClient(server_name="developer-knowledge")

# Example: search for Cloud Storage CLI flags

response = client.search_documents(
    query="gcloud storage ls --project",
    page_size=5,
)
for doc in response.documents:
    print(doc.title, doc.snippet)

The MCPClient constructor looks up the URL https://developerknowledge.googleapis.com/mcp and transport type from the internal registry populated by the .mcp.json configuration.

REST API Fallback Strategy

When the MCP handshake fails or the server is unreachable, skills fall back to the REST API as documented in skills/developers/retrieving-developer-knowledge/SKILL.md:

curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{"query":"How do I enable versioning on a Cloud Storage bucket?"}'

This fallback ensures robust operation across environments where MCP services may not be accessible. The skills/cloud/google-cloud-storage-basics/references/mcp-usage.md file provides additional concrete examples mapping MCP tool sets to equivalent CLI commands.

Summary

• MCP server plugins use .mcp.json files to declare server endpoints, transport types, and configurations in the google/skills repository.
• The Agent runtime automatically registers declared servers from plugins/cloud/google-cloud-developer/.mcp.json and exposes their tools to skills.
• Skills define tool usage patterns in their SKILL.md manifests, prioritizing MCP methods like answer_query and search_documents.
• The MCPClient Python class provides runtime access to registered servers without hardcoding connection details.
• When MCP services are unavailable, skills gracefully degrade to direct REST API calls to https://developerknowledge.googleapis.com/v1.

Frequently Asked Questions

Where are MCP server plugins defined in the Google Skills repository?

MCP server plugins are defined in JSON configuration files within plugin directories. The primary example is plugins/cloud/google-cloud-developer/.mcp.json, which declares the Developer Knowledge server with its schema, type (streamable-http), and endpoint URL. Additional configuration may appear in mcp_config.json files for runtime-specific implementations.

How does a skill know which MCP tools are available?

The Agent runtime performs tool discovery when registering the MCP server. The server advertises its capabilities via the Model Context Protocol, and the runtime injects these tools into the skill's execution context. Skill manifests in files like skills/developers/retrieving-developer-knowledge/SKILL.md document the expected tool signatures for reference and validation.

What happens if the MCP server is unreachable at runtime?

If the MCP server fails the initial handshake or becomes unavailable during execution, the skill falls back to the REST API workflow documented in its manifest. For the Developer Knowledge skill, this means switching from MCP tools like answer_query to direct HTTP POST requests against https://developerknowledge.googleapis.com/v1:answerQuery with proper OAuth authentication.

Can multiple MCP servers be registered for a single skill?

Yes. The mcpServers object in .mcp.json supports multiple named server configurations. Each entry maps a unique logical name to its connection parameters, allowing skills to access diverse tool sets—from developer documentation to cloud storage operations—through separate MCP endpoints while maintaining a unified interface.

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