mcp

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 30, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package mcp wires MCP toolsets for the workloads mast runs. Server definitions live in a catalog file (mcp.json — see Catalog); the generic NewToolset dispatches by transport kind (streamable HTTP or a local stdio process). NewGKEToolset is a convenience constructor for the GKE MCP server, the one server mast shipped wiring for first.

Index

Constants

View Source
const (
	// TransportHTTP speaks MCP over a streamable HTTP endpoint (url).
	TransportHTTP = "http"
	// TransportStdio launches a local process and speaks MCP over its
	// stdin/stdout (command + args + env).
	TransportStdio = "stdio"
)

Transport kinds a catalog entry may declare.

View Source
const (
	// EnvModeInherit (the default, also the zero value "") gives the child
	// the daemon's full environment with the configured Env layered on top.
	EnvModeInherit = "inherit"
	// EnvModeClean starts the child from an empty environment: it sees only
	// the daemon variables named in EnvPassthrough plus the configured Env.
	// Nothing else from the daemon environment leaks into the child.
	EnvModeClean = "clean"
)

Environment inheritance modes for a stdio server (ServerConfig.EnvMode).

View Source
const CatalogFileName = "mcp.json"

CatalogFileName is the well-known name of the MCP server catalog that sits alongside a workload (in a directory bundle) or at the config root (in `.agents/` mode). Workload bundles reference servers defined here by name via tool_catalog.mcp[].server; this file holds the actual transport + auth definitions.

The catalog is a privilege-bearing control-plane file: a stdio server entry names a local command mast will execute, so editing it grants code execution. It is trusted operator configuration, on par with config.json (see pkg/permissions/controlplane.go).

View Source
const CatalogVersion = 1

CatalogVersion is the only mcp.json schema version this build accepts.

View Source
const DefaultDigestThreshold = 8000

DefaultDigestThreshold is the response size, in bytes, below which a tool response bypasses the router entirely and is returned verbatim. Small responses are the common case and digesting them buys nothing but latency and a wrapped shape the model has to read through.

View Source
const DefaultGKEEndpoint = "https://container.googleapis.com/mcp"

DefaultGKEEndpoint is the public GKE MCP server URL.

View Source
const DefaultGKEScope = "https://www.googleapis.com/auth/cloud-platform"

DefaultGKEScope is the OAuth 2.0 scope the GKE MCP server accepts. Broad but matches core-agent's recipe and gke-mcp's own docs.

View Source
const RetrieveRawToolName = "retrieve_raw"

RetrieveRawToolName is the model-facing name of the escape hatch.

Variables

This section is empty.

Functions

func NewGKEToolset

func NewGKEToolset(ctx context.Context, cfg GKEConfig) (tool.Toolset, error)

NewGKEToolset builds a tool.Toolset backed by the GKE MCP server, authenticated via Google OAuth 2.0 from Application Default Credentials. Fails fast if credentials cannot be loaded or an initial token cannot be fetched — see newGoogleAuthTransport for the exact failure modes.

func NewRetrieveRawTool added in v0.5.0

func NewRetrieveRawTool(store digest.Store) (tool.Tool, error)

NewRetrieveRawTool exposes digest.Store.Get to the model as a tool.

Digesting is only safe when the model can get the original back, so this tool is the other half of WithDigest rather than an optional extra: the wiring site registers a store and this tool together, or neither. A nil store is a construction error for the same reason — a registered tool that refuses every call teaches the model nothing except that the escape hatch does not work.

The handler never returns a Go error. An unknown call_id or a broken store comes back as a normal tool response whose `raw` carries an "(error: ...)" prefix, because the model has to stay in the loop to recover: aborting the turn over a failed spot-check is a worse outcome than telling it the spot-check is unavailable.

func NewToolset added in v0.2.0

func NewToolset(ctx context.Context, name string, cfg ServerConfig) (tool.Toolset, error)

NewToolset builds a tool.Toolset for a single catalog server, dispatched by transport kind. The MCP session is established lazily on first use, so this does not launch a stdio command or open an HTTP connection — except that HTTP servers with Google OAuth pre-fetch a token at construction to fail fast on missing credentials.

The config is validated here (the same per-server checks Catalog.Validate runs), so a config built directly in code — the library-embedded path, bypassing LoadCatalog — is held to the same rules as one parsed from mcp.json. This matters for the env-scoping fields: an unrecognized EnvMode must fail closed with an error rather than silently falling back to full daemon-environment inheritance in childEnv. The catalog-level command_allowlist is not enforced here because it is a Catalog policy, not a property of a single ServerConfig.

func WithDigest added in v0.5.0

func WithDigest(ts tool.Toolset, server string, opts *DigestOptions) tool.Toolset

WithDigest wraps ts so every tool response it serves is routed through digest.Process before the model sees it. server is the mcp.json key, checked against opts.NeverServers.

It returns ts unchanged when there is nothing to do: a nil toolset, a nil opts (digesting off), or a server that opted out. That makes the wrap safe to apply unconditionally at the call site, which is where the decision is easiest to read.

Types

type AuthConfig added in v0.2.0

type AuthConfig struct {
	// GoogleOAuth authenticates via Application Default Credentials.
	GoogleOAuth *GoogleOAuthConfig `json:"google_oauth,omitempty"`
}

AuthConfig selects an authentication method for an HTTP MCP server. Exactly one method should be set; only Google OAuth is wired today.

type Catalog added in v0.2.0

type Catalog struct {
	Version int                     `json:"version"`
	Servers map[string]ServerConfig `json:"servers"`

	// CommandAllowlist, when non-empty, bounds which executables the stdio
	// servers in this catalog may launch: every stdio server's resolved
	// command (after ${VAR} expansion) must appear in this list or the
	// catalog fails validation. Allowlist entries are themselves expanded
	// before comparison, so both sides are matched post-expansion. Empty
	// (the default) imposes no restriction. Defense-in-depth for
	// deployments that want to cap the set of local processes mast can
	// spawn even when the catalog file itself is trusted.
	CommandAllowlist []string `json:"command_allowlist,omitempty"`
}

Catalog is a parsed mcp.json: a versioned map of server name to definition.

func LoadCatalog added in v0.2.0

func LoadCatalog(path string) (Catalog, error)

LoadCatalog reads and validates an mcp.json file at path. A missing file is an error — callers that may not have a catalog should check before calling.

func (Catalog) Validate added in v0.2.0

func (c Catalog) Validate() error

Validate checks the version and every server definition. It reports the first problem it finds.

type DigestOptions added in v0.5.0

type DigestOptions struct {
	// Store is the CCR backing for retrieve_raw. When nil, digesting
	// still runs but the raw payload is gone once the digest is made —
	// so the wiring site pairs a store with the retrieve_raw tool and
	// registers neither without the other.
	Store digest.Store

	// Threshold is the serialized byte size below which a response is
	// returned unwrapped — not digested-then-passed-through, but
	// handed back in the tool's own shape. Zero means
	// DefaultDigestThreshold. See Run for why the distinction matters.
	Threshold int

	// NeverServers names catalog servers (by mcp.json key) that opt out
	// of digesting, from their `no_digest: true`. The check runs at
	// wrap time rather than per call, so an opted-out server's tools
	// are the unwrapped originals — no per-call branch, and nothing
	// downstream can tell a never-server's tool from an unwrapped one.
	NeverServers map[string]bool

	// OnResult, when non-nil, fires after every successful Process call
	// with the fully-populated Result. Runs synchronously on the tool's
	// own goroutine, so a callback that does I/O adds latency to every
	// tool call: increment counters, nothing more.
	OnResult func(*digest.Result)
}

DigestOptions configures how WithDigest routes MCP tool responses through pkg/digest. A nil *DigestOptions disables wrapping entirely, which is what --mcp-digest=false hands the wiring site.

There is no LLMFallback field. Upstream has one — an opt-in small-tier subagent that compresses prose the structural pruner cannot reduce — and mast does not port it: it would need a resolved small-tier model, a second billing path inside a tool call, and a budget story for spend the session's meter never sees. mast's wrap is structural-only, so a payload the pruner cannot reduce takes pkg/digest's bounded passthrough (digest.MaxPassthroughBytes) and digest.Savings.Subagent* stay zero here by construction.

type GKEConfig

type GKEConfig struct {
	// Endpoint is the MCP server URL. Defaults to DefaultGKEEndpoint.
	Endpoint string

	// Scopes is the list of OAuth 2.0 scopes to request on the
	// access token. Defaults to []string{DefaultGKEScope}.
	Scopes []string

	// ToolFilter, when non-nil, restricts which of the server's tools
	// are exposed to the agent. Applied at first-fetch time by
	// mcptoolset.
	ToolFilter tool.Predicate

	// Name is a diagnostic label for the toolset. Defaults to "gke".
	Name string
}

GKEConfig configures the GKE MCP toolset.

type GoogleOAuthConfig added in v0.2.0

type GoogleOAuthConfig struct {
	// Scopes are the OAuth 2.0 scopes to request. Empty defaults to
	// DefaultGKEScope.
	Scopes []string `json:"scopes,omitempty"`
}

GoogleOAuthConfig configures ADC-based bearer auth for an HTTP server.

type ServerConfig added in v0.2.0

type ServerConfig struct {
	// Transport is the wire mechanism: TransportHTTP or TransportStdio.
	Transport string `json:"transport"`

	// URL is the streamable-HTTP endpoint (TransportHTTP only).
	URL string `json:"url,omitempty"`
	// Auth describes how to authenticate to an HTTP server. nil means
	// the endpoint needs no credentials.
	Auth *AuthConfig `json:"auth,omitempty"`

	// Command is the executable to launch (TransportStdio only). May be a
	// bare name resolved on PATH or an absolute path. Expanded like Args.
	Command string `json:"command,omitempty"`
	// Args are the command's arguments (TransportStdio only). ${VAR}
	// references are expanded against the daemon environment via
	// os.ExpandEnv, so bare $name expands too and there is no escape for a
	// literal $ (see ServerConfig.ResolvedCommand).
	Args []string `json:"args,omitempty"`
	// Env sets environment variables for the child process (TransportStdio
	// only). Values are expanded the same way as Args; a value needing a
	// literal $ should come from the inherited daemon environment instead.
	// How Env combines with the daemon environment depends on EnvMode.
	Env map[string]string `json:"env,omitempty"`

	// EnvMode controls how the child's environment is built (TransportStdio
	// only): "" or "inherit" (default) gives the child the daemon's full
	// environment with Env layered on top; "clean" starts the child from an
	// empty environment so it sees only EnvPassthrough plus Env. Use "clean"
	// to keep unrelated daemon secrets out of a local MCP server — but then
	// list the vars it genuinely needs (e.g. PATH, HOME) in EnvPassthrough.
	EnvMode string `json:"env_mode,omitempty"`
	// EnvPassthrough lists daemon environment variable names to copy into
	// the child verbatim when EnvMode is "clean" (TransportStdio only). It
	// is rejected under inherit mode — where the child already inherits
	// everything, a passthrough list would give a false sense of scoping.
	EnvPassthrough []string `json:"env_passthrough,omitempty"`

	// NoDigest opts this server out of the MCP digest wrap, so its tool
	// responses reach the model exactly as the server sent them (both
	// transports). The daemon-wide switch is --mcp-digest; this is the
	// per-server escape hatch for a server whose responses are small
	// enough that digesting is pure overhead, or whose exact bytes are
	// what the specialist is there to read.
	//
	// It is not validated against anything: opting out of a size
	// optimization cannot be a misconfiguration, and a catalog written
	// for a build with the wrap disabled must still load.
	NoDigest bool `json:"no_digest,omitempty"`
}

ServerConfig defines a single MCP server. The fields that apply depend on Transport: HTTP reads URL + Auth; stdio reads Command + Args + Env.

func (ServerConfig) ResolvedCommand added in v0.2.0

func (cfg ServerConfig) ResolvedCommand() (string, []string)

ResolvedCommand returns the executable and arguments a stdio server will launch, with ${VAR} references expanded against the daemon environment. Exposed so the wiring site can audit-log exactly what will run (command *and* args — the security-relevant payload often lives in the args) before the lazy launch.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL