Skip to main content
MCP servers extend your agent with external tools that work identically to built-in tools across Run, Stream, RunAsync, and approval gates. At NewAgent, the SDK connects to each server, discovers tools, applies any tool filter, and validates the setup — failing fast if a server is unreachable.
MCP tool names use the prefix mcp_<serverKey>_<toolName> — for example, a server named "remote" with a search tool registers as mcp_remote_search. This prevents collisions when multiple servers expose tools with the same logical name.

​
Register MCP servers

Two equivalent paths. Use one or combine both — server names must be unique across both.

​
WithMCPConfig

Declare servers in a map — key is the stable server name: 
import (
    "time"
    "github.com/agenticenv/agent-sdk-go/pkg/agent"
    "github.com/agenticenv/agent-sdk-go/pkg/mcp"
)

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithMCPConfig(agent.MCPServers{
        "local": {
            Transport: mcp.MCPStdio{
                Command: "node",
                Args:    []string{"path/to/mcp-server.js"},
            },
            Timeout: 60 * time.Second,
        },
        "remote": {
            Transport: mcp.MCPStreamableHTTP{
                URL:   "https://mcp.example.com/mcp",
                Token: os.Getenv("MCP_TOKEN"), // bearer token
            },
            ToolFilter:    mcp.MCPToolFilter{AllowTools: []string{"search", "wiki"}},
            Timeout:       30 * time.Second,
            RetryAttempts: 3,
        },
    }),
)

​
WithMCPClients

Build clients with pkg/mcp/client for custom transport or pre-connected clients: 
import mcpclient "github.com/agenticenv/agent-sdk-go/pkg/mcp/client"

cl, err := mcpclient.NewClient("local",
    mcp.MCPStdio{Command: "node", Args: []string{"path/to/mcp-server.js"}},
    mcpclient.WithTimeout(60*time.Second),
    mcpclient.WithToolFilter(mcp.MCPToolFilter{AllowTools: []string{"search"}}),
)
if err != nil {
    return err
}

a, err := agent.NewAgent(
    agent.WithLLMClient(llmClient),
    agent.WithMCPClients(cl),
)
The packaged client is built on the official Go MCP SDK.

​
Transports

TransportTypeUse case
Stdiomcp.MCPStdioLocal subprocess — requires Node or another runtime for the MCP server process
Streamable HTTPmcp.MCPStreamableHTTPRemote server — supports Token, OAuthClientCreds, custom Headers, SkipTLSVerify
Stdio prerequisite: the MCP server runs as a subprocess. You need the server’s runtime installed (e.g. Node for npm-based servers, Python for uv/pip-based servers). The SDK launches and manages the subprocess — you only provide Command and Args.
Remote MCP servers widen the tool surface available to your LLM. In production:
  • Prefer TLS for streamable HTTP — avoid SkipTLSVerify outside local development
  • Store bearer tokens, OAuth credentials, and custom headers in environment variables or a secrets manager
  • Use ToolFilter to allowlist only the tools your agent actually needs

​
MCPConfig fields

FieldDescription
TransportStdio or streamable HTTP config from pkg/mcp
ToolFilterAllowTools or BlockTools — applied at tool discovery
TimeoutPer-call timeout — zero uses client default
RetryAttemptsRetry count for transient failures

​
Runtime changes

Add or remove MCP servers after NewAgent via a.MCPRegistry() — the next run picks up the current registry state.
Dynamic registry changes on the agent client process do not automatically propagate to a remote worker process. For split client/worker deployments, register matching MCP servers on both NewAgent and NewAgentWorker, or ensure workers see the same registry state before runs execute.

​
Examples

MCP Config

WithMCPConfig from environment

MCP Client

WithMCPClients with explicit clients

Tools

Native and custom tool registration

Approvals

MCP tools follow the same approval policy

Dynamic Capabilities

Register MCP servers at runtime

Production Readiness

MCP security checklist