set.go

Overview

The set.go file implements an MCP (Model Context Protocol) ToolSet adapter that integrates MCP-compliant tools into the ADK agent tooling system. This adapter enables an agent, typically an LLM agent, to dynamically discover, retrieve, and invoke tools hosted on a remote MCP server transparently as native tools within the ADK framework.

The MCP ToolSet connects to an MCP server via an MCP client session, lazily established on first use, fetches the list of available MCP tools, converts them into ADK-compatible tools, and exposes them to the agent. Tool invocation requests are delegated through the MCP session to the MCP server, with results adapted back to the ADK tool output format.

This file is central to the MCP Toolset Integration subtopic and a key component of the broader Tooling System that allows agents to extend their capabilities by incorporating external MCP tools.

Key Components

Config Struct

Config encapsulates the initialization parameters for creating an MCP ToolSet:

• Client (*mcp.Client): Optional custom MCP client. If nil, a default client is created with a built-in implementation name and version.

• Transport (mcp.Transport): Required transport to connect to the MCP server. This handles command or network communication with the MCP server.

• ToolFilter (tool.Predicate): Optional predicate function to filter which MCP tools to expose. If nil, all tools are included. Useful for limiting tools by name or other criteria.

New Function

func New(cfg Config) (tool.Toolset, error)

Creates and returns a new MCP ToolSet instance configured with the provided Config. It ensures a client exists (creating a default if needed), attaches the transport and tool filter, and returns a tool.Toolset implementation.

Usage Example

ts, err := mcptoolset.New(mcptoolset.Config{
    Transport: &mcp.CommandTransport{Command: exec.Command("myserver")},
})
if err != nil {
    // handle error
}

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

This example shows how to create an MCP ToolSet with a command transport and inject it into an LLM agent configuration.

set Struct

The set struct implements the tool.Toolset interface and encapsulates state and logic for managing an MCP client session and providing MCP tools to the agent.

Fields

• client (mcp.Client): MCP client used to establish sessions and communicate with the MCP server.

• transport (mcp.Transport): Transport used to connect to the MCP server.

• toolFilter (tool.Predicate): Optional filter function to select which tools to expose.

• mu (sync.Mutex): Mutex protecting concurrent access to session.

• session (*mcp.ClientSession): Cached MCP client session, lazily initialized.

Methods of set

Name() string

Returns the name of the toolset, "mcp_tool_set".

Description() string

Returns a human-readable description of the toolset:
"Connects to a MCP Server, retrieves MCP Tools into ADK Tools."

IsLongRunning() bool

Returns false indicating the toolset itself is not considered long-running.

Tools(ctx agent.ReadonlyContext) ([]tool.Tool, error)

Fetches MCP tools from the MCP server, converts them to ADK tool.Tool instances, and applies the optional toolFilter.

Process:

1. Obtains an MCP client session via getSession.

2. Uses the MCP session's ListTools API to paginate through all available MCP tools.

3. Converts each MCP tool to an ADK tool via convertTool (defined elsewhere).

4. Filters tools using toolFilter if provided.

5. Accumulates and returns the list of ADK tools.

Returns:

• A slice of tool.Tool instances representing the converted MCP tools.

• An error if fetching or conversion fails.

getSession(ctx context.Context) (*mcp.ClientSession, error)

Manages the lifecycle of the MCP client session with concurrency safety.

Behavior:

• Locks the mutex mu to ensure single initialization.

• If a session already exists, returns it.

• Otherwise, calls client.Connect with the configured transport to establish a new session.

• Caches the session for reuse.

• Returns the session or an error if the connection fails.

Important Implementation Details

• Lazy Session Initialization: The MCP client session is created on-demand when the first tool retrieval or invocation occurs. This avoids unnecessary connections and resource usage if no tools are requested.

• Pagination Handling: The Tools method handles paginated responses from ListTools by looping until NextCursor is empty, ensuring complete retrieval of all MCP tools.

• Tool Conversion: Conversion from MCP tools to ADK tools is done through a helper function convertTool, which wraps MCP tool metadata and functionality into the ADK tool interface. This conversion adapts schemas and call semantics.

• Filtering: Optional filtering via a predicate allows only selected MCP tools to be exposed, enabling fine-grained control over tool availability.

• Concurrency Safety: Use of a mutex ensures safe concurrent access to the MCP session state.

Interactions with Other System Components

• MCP Client and Server: The MCP ToolSet depends on the MCP client SDK (github.com/modelcontextprotocol/go-sdk/mcp) to communicate with the MCP server, managing sessions and tool calls.

• ADK Tooling System: Implements the tool.Toolset interface, allowing MCP tools to be seamlessly integrated into the ADK agent tooling system.

• LLM Agents: The MCP ToolSet is typically passed as part of the Toolsets array in an llmagent.Config (LLM Integration and Agents), enabling LLM agents to invoke MCP tools as native tools.

• Transport Layer: Uses an MCP Transport implementation for communication, commonly a command transport wrapping an external MCP server process.

Mermaid Class Diagram

classDiagram
class set {
-client: *mcp.Client
-transport: mcp.Transport
-toolFilter: tool.Predicate
-mu: sync.Mutex
-session: *mcp.ClientSession
+Name() string
+Description() string
+IsLongRunning() bool
+Tools(ctx agent.ReadonlyContext) []tool.Tool
-getSession(ctx context.Context) *mcp.ClientSession
}
class Config {
+Client: *mcp.Client
+Transport: mcp.Transport
+ToolFilter: tool.Predicate
}
set ..> Config : uses

Workflow of Tool Retrieval and Session Management

sequenceDiagram
participant Agent
participant MCP_ToolSet as ToolSet
participant MCP_Session as Session
participant MCP_Server as Server
Agent->>ToolSet: Tools(ctx)
ToolSet->>ToolSet: getSession(ctx)
alt session exists
ToolSet-->>Agent: session
else
ToolSet->>Session: Connect(transport)
Session->>Server: Establish connection
Server-->>Session: Connection established
Session-->>ToolSet: session
ToolSet-->>Agent: session
end
ToolSet->>Session: ListTools(cursor)
Session->>Server: ListTools request with cursor
Server-->>Session: Tools list + NextCursor
Session-->>ToolSet: Tools response
ToolSet->>ToolSet: convertTool each tool
ToolSet-->>Agent: []tool.Tool

This sequence shows:

• The agent requests tools from the MCP ToolSet.

• The ToolSet ensures an MCP session is established (lazily).

• It fetches tools from the MCP server using pagination.

• Converts MCP tools to ADK tools.

• Returns the tool list to the agent.

References to Related Topics

• Tooling System — Defines the modular framework for tools and toolsets including interfaces and predicates.

• MCP Toolset Integration — Provides detailed context on the MCP ToolSet purpose, usage, and integration.

• LLM Integration and Agents — Describes how toolsets like this MCP ToolSet are incorporated into LLM agents.

• Agent Invocation Context — Provides context interfaces used when retrieving tools.

• Tool Predicate — Used for filtering tools based on names or other criteria.

• MCP Client SDK — Underlying protocol and client implementation used for communication.

This documentation covers the design, implementation, usage, and integration of the MCP ToolSet adapter implemented in set.go. It provides the necessary understanding to use and extend the MCP ToolSet within the agent tooling system.