The highest tagged major version is
Documentation
¶
Overview ¶
Package mcp wires user-configured Model Context Protocol servers into the agent loop.
At startup the host calls Build, which reads .agents/mcp.json, spawns each declared server (stdio child or Streamable HTTP client), wraps the resulting MCP toolsets via ADK's google.golang.org/adk/tool/mcptoolset, and returns:
- the toolsets, so they can be passed to agent.New(WithToolsets…)
- per-server records the host can render (e.g. a /mcp slash command).
Failures are non-fatal: a server whose process won't start surfaces in the per-server record with its error; the agent continues with whichever servers did connect.
Index ¶
- Constants
- func DeclineHandler(serverName string, send func(string)) func(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
- func InterpolateEnv(s string) string
- func InterpolateMap(m map[string]string) map[string]string
- func SetImplementationName(name string)
- type AuthSpec
- type ElicitorFn
- type GoogleOAuthAuth
- type Server
- type ServerSpec
- type Servers
Constants ¶
const ( StatusOK = "ok" StatusError = "error" )
Status values surfaced via the per-server records.
const MCPFileName = "mcp.json"
MCPFileName is the project-local MCP config file inside .agents/.
Variables ¶
This section is empty.
Functions ¶
func DeclineHandler ¶
func DeclineHandler(serverName string, send func(string)) func(context.Context, *mcp.ElicitRequest) (*mcp.ElicitResult, error)
DeclineHandler returns an MCP elicitation handler that declines every request and emits a one-line notice through send. Used as the fallback when no interactive elicitor is wired.
func InterpolateEnv ¶
InterpolateEnv replaces ${env:NAME} placeholders in s by looking each NAME up via os.Getenv. Unset values pass through as empty strings — same semantics shells use.
func InterpolateMap ¶
InterpolateMap returns a copy of m with each value run through InterpolateEnv. Used for ServerSpec.Env and ServerSpec.Headers.
func SetImplementationName ¶
func SetImplementationName(name string)
SetImplementationName overrides the name reported during the MCP client handshake. Useful for hosts that want to identify themselves to the server. Call before Build.
Types ¶
type AuthSpec ¶ added in v1.5.0
type AuthSpec struct {
GoogleOAuth *GoogleOAuthAuth `json:"google_oauth,omitempty"`
}
AuthSpec selects an authentication strategy for an HTTP MCP server. Exactly one inner field may be set. Future strategies (audience- scoped ID tokens for Cloud Run / IAP, mTLS, etc.) slot in as sibling pointers.
type ElicitorFn ¶
type ElicitorFn func(ctx context.Context, serverName string, req *mcp.ElicitRequest) (*mcp.ElicitResult, error)
ElicitorFn is the host-supplied bridge that turns a server's elicitation request into a user response. Interactive hosts plug in a function that opens a prompt and blocks; the headless path leaves it nil and falls back to DeclineHandler.
The implementation must respect ctx — if it returns ctx.Err the SDK translates that into a protocol-level cancel.
type GoogleOAuthAuth ¶ added in v1.5.0
type GoogleOAuthAuth struct {
// Scopes is the OAuth 2.0 scopes requested on the access token.
// No default — each server documents its own scope requirements,
// and an implicit broad default (e.g. cloud-platform) would grant
// more privilege than necessary. Explicit is safer.
//
// For the GKE MCP server, typical values:
// https://www.googleapis.com/auth/container.read-only
// https://www.googleapis.com/auth/container
Scopes []string `json:"scopes"`
}
GoogleOAuthAuth authenticates outbound MCP requests with a Google OAuth 2.0 access token sourced from Application Default Credentials. Suitable for Google-hosted API endpoints that accept scoped access tokens (e.g. the GKE MCP server at container.googleapis.com/mcp).
For audience-scoped ID-token auth (Cloud Run / IAP / custom OIDC), add a sibling GoogleIDToken field when a consumer needs it.
func (*GoogleOAuthAuth) Validate ¶ added in v1.5.0
func (g *GoogleOAuthAuth) Validate(name string) error
Validate reports whether the GoogleOAuthAuth is usable.
type Server ¶
type Server struct {
Name string
Status string
Tools []string // tool names exposed; populated lazily by Toolset
Err error // non-nil when Status == StatusError
// contains filtered or unexported fields
}
Server is one configured MCP server's runtime state.
func Build ¶
func Build(ctx context.Context, agentsDir string, send func(string), gate *permissions.Gate, elicitor ElicitorFn) ([]*Server, []tool.Toolset, error)
Build reads .agents/mcp.json and starts every declared server in parallel. The send callback is plumbed into each server's elicitation handler (when no interactive elicitor is provided) so the host can surface elicitation requests in the right place.
gate (optional) gates each MCP tool call through the permission system so MCP tools are subject to the same ask/allow/yolo rules as built-in tools. Pass nil to skip gating.
elicitor (optional) is the interactive bridge for elicitation requests. Headless callers leave it nil and fall back to the decline-with-notice stub.
Servers that fail to start come back with Status==StatusError so they're visible without breaking the rest of the agent.
type ServerSpec ¶
type ServerSpec struct {
Transport string `json:"transport"` // "stdio" | "http"
Command string `json:"command,omitempty"` // stdio
Args []string `json:"args,omitempty"` // stdio
Env map[string]string `json:"env,omitempty"` // stdio
URL string `json:"url,omitempty"` // http
Headers map[string]string `json:"headers,omitempty"` // http
Auth *AuthSpec `json:"auth,omitempty"` // http
}
ServerSpec describes one MCP server. Either Command (stdio) or URL (Streamable HTTP) must be set; we intentionally don't support both.
func (ServerSpec) Validate ¶
func (s ServerSpec) Validate(name string) error
Validate checks that the spec describes a single, complete transport.
type Servers ¶
type Servers struct {
Version int `json:"version"`
Servers map[string]ServerSpec `json:"servers"`
}
Servers is the on-disk schema for .agents/mcp.json.
Source Files