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

> Learn how MCP server plugins integrate with Google Agent Skills. Discover automatic registration of MCP endpoints as callable tools and fallback to REST APIs.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: integration-guide
- Published: 2026-09-04

---

**MCP server plugins declare external Model Context Protocol endpoints in [`.mcp.json`](https://github.com/google/skills/blob/main/.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`](https://github.com/google/skills/blob/main/.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`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/.mcp.json), the Developer Knowledge MCP server is declared with its transport type and endpoint:

```json
{
  "$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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/developers/retrieving-developer-knowledge/SKILL.md) manifest defines the tool selection hierarchy:

```markdown

## 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:

```python
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`](https://github.com/google/skills/blob/main/.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`](https://github.com/google/skills/blob/main/skills/developers/retrieving-developer-knowledge/SKILL.md):

```bash
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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/.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`](https://github.com/google/skills/blob/main/plugins/cloud/google-cloud-developer/.mcp.json) and exposes their tools to skills.
- Skills define tool usage patterns in their [`SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/.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.