mcp

Documentation

Overview

Package mcp implements the client foundation for consuming Model Context Protocol servers from glue hosts.

This package follows ADR-0011. It supports JSON-RPC lifecycle negotiation over stdio and Streamable HTTP, discovery of MCP server tools, mapping those tools to permission-gated glue.Tool values, read-only resource metadata inspection, permission-gated resource reads, and prompt inspection. Sampling, elicitation, OAuth, and dynamic discovery are deferred follow-up surfaces.

Index

• Constants
• type Client
  • func NewClient(ctx context.Context, cfg ServerConfig) (*Client, error)
  • func NewHTTPClient(ctx context.Context, cfg ServerConfig) (*Client, error)
  • func NewStdioClient(ctx context.Context, cfg ServerConfig) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) InitializeResult() InitializeResult
  • func (c *Client) Notify(ctx context.Context, method string, params any) error
  • func (c *Client) Request(ctx context.Context, method string, params any, result any) error
  • func (c *Client) Stderr() string
• type Implementation
• type InitializeResult
• type Manager
  • func NewManager(ctx context.Context, configs []ServerConfig, _ Options) (*Manager, error)
  • func (m *Manager) Close() error
  • func (m *Manager) GetPrompt(ctx context.Context, serverName, name string, args map[string]string) (PromptGet, error)
  • func (m *Manager) Prompts(ctx context.Context) ([]Prompt, error)
  • func (m *Manager) ReadResource(ctx context.Context, serverName, uri string) (ResourceRead, error)
  • func (m *Manager) Resources(ctx context.Context) ([]Resource, error)
  • func (m *Manager) Tools() []glue.Tool
• type Options
• type Prompt
• type PromptArgument
• type PromptGet
• type PromptMessage
• type RPCError
  • func (e *RPCError) Error() string
• type Resource
• type ResourceContent
• type ResourceRead
• type ServerConfig

Constants

const (
	// TransportStdio launches an MCP server subprocess over stdin/stdout.
	TransportStdio = "stdio"
	// TransportHTTP uses MCP Streamable HTTP against a configured endpoint.
	TransportHTTP = "http"
)

const ProtocolVersion = "2025-11-25"

ProtocolVersion is the MCP protocol version this package speaks.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is one initialized MCP client session.

func NewClient

func NewClient(ctx context.Context, cfg ServerConfig) (*Client, error)

NewClient starts the configured MCP transport and completes lifecycle negotiation. Empty cfg.Transport defaults to stdio.

func NewHTTPClient

func NewHTTPClient(ctx context.Context, cfg ServerConfig) (*Client, error)

NewHTTPClient connects to a Streamable HTTP MCP server and completes lifecycle negotiation.

func NewStdioClient

func NewStdioClient(ctx context.Context, cfg ServerConfig) (*Client, error)

NewStdioClient starts a stdio MCP server and completes lifecycle negotiation.

func (*Client) Close

func (c *Client) Close() error

Close releases the underlying transport.

func (*Client) InitializeResult

func (c *Client) InitializeResult() InitializeResult

InitializeResult returns the negotiated server information.

func (*Client) Notify

func (c *Client) Notify(ctx context.Context, method string, params any) error

Notify sends a JSON-RPC notification.

func (*Client) Request

func (c *Client) Request(ctx context.Context, method string, params any, result any) error

Request sends a JSON-RPC request and decodes the result into result when result is non-nil.

func (*Client) Stderr

func (c *Client) Stderr() string

Stderr returns retained stderr diagnostics for stdio transports.

type Implementation

type Implementation struct {
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`
}

Implementation describes an MCP peer.

type InitializeResult

type InitializeResult struct {
	ProtocolVersion string         `json:"protocolVersion"`
	Capabilities    map[string]any `json:"capabilities,omitempty"`
	ServerInfo      Implementation `json:"serverInfo,omitempty"`
	Instructions    string         `json:"instructions,omitempty"`
}

InitializeResult is the portion of MCP initialize results needed by this package.

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns initialized MCP clients and exposes their discovered tools as ordinary glue tools.

func NewManager

func NewManager(ctx context.Context, configs []ServerConfig, _ Options) (*Manager, error)

NewManager initializes each configured MCP server, discovers its tools, and maps them to glue.Tool values.

func (*Manager) Close

func (m *Manager) Close() error

Close releases all MCP client transports owned by the manager.

func (*Manager) GetPrompt

func (m *Manager) GetPrompt(ctx context.Context, serverName, name string, args map[string]string) (PromptGet, error)

GetPrompt renders a prompt by name from one named configured MCP server.

func (*Manager) Prompts

func (m *Manager) Prompts(ctx context.Context) ([]Prompt, error)

Prompts lists prompt metadata from servers that advertise MCP prompt support.

func (*Manager) ReadResource

func (m *Manager) ReadResource(ctx context.Context, serverName, uri string) (ResourceRead, error)

ReadResource reads a resource URI from one named configured MCP server.

func (*Manager) Resources

func (m *Manager) Resources(ctx context.Context) ([]Resource, error)

Resources lists resource metadata from servers that advertise MCP resource support. It does not read resource contents.

func (*Manager) Tools

func (m *Manager) Tools() []glue.Tool

Tools returns the discovered glue tools.

type Options

type Options struct{}

Options configures an MCP manager. It is intentionally empty for the first stdio/tool-mapping slice so future compatibility options have a stable home.

type Prompt

type Prompt struct {
	Server      string           `json:"server"`
	Name        string           `json:"name"`
	Title       string           `json:"title,omitempty"`
	Description string           `json:"description,omitempty"`
	Arguments   []PromptArgument `json:"arguments,omitempty"`
}

Prompt describes an MCP prompt exposed by one configured server.

type PromptArgument

type PromptArgument struct {
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

PromptArgument describes one named prompt argument.

type PromptGet

type PromptGet struct {
	Server      string          `json:"server"`
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Messages    []PromptMessage `json:"messages"`
}

PromptGet contains messages returned by an MCP prompts/get call.

type PromptMessage

type PromptMessage struct {
	Role    string          `json:"role"`
	Content json.RawMessage `json:"content"`
}

PromptMessage is one role/content pair returned by a prompt.

type RPCError

type RPCError struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    json.RawMessage `json:"data,omitempty"`
}

RPCError is a JSON-RPC error returned by an MCP server.

func (*RPCError) Error

func (e *RPCError) Error() string

type Resource

type Resource struct {
	Server      string         `json:"server"`
	URI         string         `json:"uri"`
	Name        string         `json:"name"`
	Title       string         `json:"title,omitempty"`
	Description string         `json:"description,omitempty"`
	MIMEType    string         `json:"mime_type,omitempty"`
	Annotations map[string]any `json:"annotations,omitempty"`
	Size        *int64         `json:"size,omitempty"`
}

Resource describes an MCP resource exposed by one configured server.

type ResourceContent

type ResourceContent struct {
	URI      string         `json:"uri"`
	MIMEType string         `json:"mime_type,omitempty"`
	Text     *string        `json:"text,omitempty"`
	Blob     *string        `json:"blob,omitempty"`
	Meta     map[string]any `json:"_meta,omitempty"`
}

ResourceContent is one text or blob content item returned from a resource.

type ResourceRead

type ResourceRead struct {
	Server   string            `json:"server"`
	URI      string            `json:"uri"`
	Contents []ResourceContent `json:"contents"`
}

ResourceRead contains the contents returned by an MCP resources/read call.

type ServerConfig

type ServerConfig struct {
	Name string

	// Transport is "stdio" or "http". Empty means "stdio" for backward
	// compatibility with the first MCP client slice.
	Transport string

	// Stdio transport fields. Command is argv[0], never a shell string.
	Command string
	Args    []string
	Env     []string
	WorkDir string

	// HTTP transport fields. URL is the MCP endpoint. Headers are already
	// resolved static header values; callers should keep secrets out of logs.
	URL     string
	Headers map[string]string

	// Timeout caps lifecycle and request waits when callers do not supply a
	// tighter context deadline.
	Timeout time.Duration

	// MaxStderrBytes caps retained stderr diagnostics from stdio servers.
	MaxStderrBytes int
}

ServerConfig configures one MCP server connection.