MCP Toolset Integration

Purpose

The MCP Toolset Integration subtopic addresses the need to seamlessly incorporate external tools that conform to the Model Context Protocol (MCP) into agents within the modular tooling system. MCP defines a standardized protocol for model context manipulation and tool invocation, enabling diverse tools to be exposed in a uniform way.

Within the broader scope of the Tooling System, which defines various types of tools callable by agents or LLMs, this subtopic specifically enables:

• Dynamic discovery and loading of MCP-compliant tools from a remote MCP server.

• Transparent adaptation of MCP tools into the ADK's tool interfaces.

• Delegation of tool execution requests from agents to MCP tools while managing protocol communication and response handling.

This integration allows agents to leverage a rich ecosystem of MCP tools without custom wrappers for each tool, enhancing extensibility and interoperability in the agent tooling framework.

Functionality

The MCP Toolset Integration implements an adapter pattern that connects an MCP server's toolset to the ADK agent tooling system. Its key functional components and flows include:

1. MCP Session Management

• A single MCP client session is lazily established on the first interaction, using a configured mcp.Transport to connect to the MCP server.

• The session is cached for reuse, ensuring efficient communication.

2. Tool Discovery and Conversion

• The MCP ToolSet fetches the list of available MCP tools via the MCP session’s ListTools API.

• Each MCP tool is converted into an ADK tool.Tool instance by wrapping MCP tool metadata and exposing them as function tools with JSON schemas describing inputs and outputs.

• Optional filtering (ToolFilter) can limit which MCP tools are exposed to the agent.

3. Tool Execution Delegation

• When an MCP tool is invoked by the agent (via the Run method), the call is forwarded to the MCP session’s CallTool API with the provided arguments.

• The tool adapter handles error detection and response parsing:

  • If the MCP tool call returns an error, it extracts textual error details.

  • Otherwise, structured content or plain text results are converted to the ADK tool output format.

4. Integration with Agents

• The MCP ToolSet is provided as a tool.Toolset to LLM-based agents (LLM Integration and Agents), allowing agents to call MCP tools as if they were native tools.

• It supports standard tooling features such as declaring function signatures (Declaration) and request processing.

Example Usage Snippet

ts, err := mcptoolset.New(mcptoolset.Config{
    Transport: myMCPTransport,
})

agent, err := llmagent.New(llmagent.Config{
    Name:    "weather_agent",
    Model:   model,
    Toolsets: []tool.Toolset{ ts },
})

This example shows how to set up the MCP ToolSet with a transport to connect to an MCP server and inject it into an LLM agent's toolset.

Key Methods

• (*set) Tools: Retrieves and converts MCP tools into ADK tools.

• (*mcpTool) Run: Executes the MCP tool call via the MCP client session.

• getSession: Manages MCP client session lifecycle with concurrency-safe lazy initialization.

Integration

The MCP Toolset Integration complements the parent Tooling System by enabling a new category of tools based on the MCP standard. It fits alongside other subtopics such as:

• Function Tools — Wrapping native Go functions.

• Artifact Loading Tools — For session artifact management.

• Google Search Tool — External search integration.

By providing a unified adapter, MCP tools become first-class citizens in the agent tooling ecosystem, accessible through the same invocation and lifecycle patterns.

Within the larger LLM Integration and Agents topic, it enables agents to dynamically extend their capabilities with externally maintained MCP tools without manual coding per tool, fostering modularity and ease of extension.

Diagram

sequenceDiagram
participant Agent
participant MCP_ToolSet
participant MCP_Session
participant MCP_Server
Agent->>MCP_ToolSet: Request list of tools
MCP_ToolSet->>MCP_Session: ListTools API call
MCP_Session->>MCP_Server: Request tool list
MCP_Server-->>MCP_Session: Tool metadata response
MCP_Session-->>MCP_ToolSet: Tool list
MCP_ToolSet-->>Agent: Converted ADK tools
Agent->>MCP_ToolSet: Invoke MCP tool with args
MCP_ToolSet->>MCP_Session: CallTool API call
MCP_Session->>MCP_Server: Execute tool
MCP_Server-->>MCP_Session: Tool execution result
MCP_Session-->>MCP_ToolSet: Result
MCP_ToolSet-->>Agent: Parsed tool output or error

This sequence diagram illustrates the core interaction flow between an agent, the MCP toolset adapter, the MCP client session, and the remote MCP server during tool discovery and invocation.