mcpx

Documentation

Overview

Package mcpx is the mountable MCP (Model Context Protocol) server kernel: it turns a product's app into an agent-operable control plane by exposing intent-level tools over the streamable-HTTP MCP transport.

The mount is env-gated and silent by default (same contract as platform/metrics): with Enabled=false the mount is inert and the port disappears. Auth is NOT built in — mount the handler behind webx.Authenticate + webx.RequireScope so PAT callers are scoped and browser sessions can be excluded (or allowed) per product policy. See docs/adr/0014-agent-eyes-and-hands.md for the shape rationale: ploykit is a framework, so "the framework's MCP server" is a component mounted into each product's app, not a hosted service; agents connect to the product app they are developing.

Index

• func RawArgs(req *mcp.CallToolRequest, into any) error
• func ToolResultText(s string) (*mcp.CallToolResult, error)
• type Config
• type Mount
  • func NewMount(cfg Config, register func(s *mcp.Server)) *Mount
  • func (m *Mount) Handler() http.Handler
  • func (m *Mount) Path() string
  • func (m *Mount) Server() *mcp.Server

Functions

func RawArgs

func RawArgs(req *mcp.CallToolRequest, into any) error

RawArgs is a convenience for raw-schema tools: unmarshal the request's raw arguments into a typed struct. Used by framework-internal tools whose input shape is declared via a hand-written JSON schema.

func ToolResultText

func ToolResultText(s string) (*mcp.CallToolResult, error)

ToolResultText builds a plain-text tool result. Errors inside tool handlers should return (nil, out, err) and let the SDK pack them as tool errors; this helper is for the success path where the caller has a formatted string (e.g. JSON) to hand back.

Types

type Config

type Config struct {
	// Enabled gates the whole surface. nil counts as false (silent
	// degradation); the mount returns an inert 404 handler instead of a
	// live endpoint.
	Enabled *bool
	// Path is the mount point. Defaults to "/mcp".
	Path string
	// ServerName/ServerVersion identify the MCP server in initialize.
	// Defaults: "ploykit" and "0.0.0-dev".
	ServerName    string
	ServerVersion string
}

Config gates and shapes the mount.

type Mount

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

Mount is the assembled MCP surface. Mount it on the shared mux with .Handler() at .Path(), and gate it with auth middleware before serving.

func NewMount

func NewMount(cfg Config, register func(s *mcp.Server)) *Mount

NewMount assembles the mount. tools registers the built-in tools (each product adds its own via Mount.Server() before serving traffic — tool registration must happen before the first session, or rely on the SDK's tools/list_changed notification).

func (*Mount) Handler

func (m *Mount) Handler() http.Handler

Handler serves the MCP streamable-HTTP endpoint. When the mount is disabled it answers 404 (like metrics' token gate — indistinguishable from a missing route).

The endpoint runs in Stateless mode: every POST is self-contained, so the product's HTTP middleware chain (Authenticate, RequireScope) evaluates the caller on every request and context values it installs (Principal, request id) flow into tool handlers — the sessionful transport would only carry headers. That is the right shape for a control plane embedded in a product app: no session affinity, no server-side session state, auth semantics identical to the product's other API routes.

func (*Mount) Path

func (m *Mount) Path() string

Path is the configured mount point (always non-empty, even when disabled, so wiring code can mux.Handle unconditionally).

func (*Mount) Server

func (m *Mount) Server() *mcp.Server

Server exposes the underlying SDK server so the product (or framework packages like devx) can register additional tools with mcp.AddTool. Panics when the mount is disabled — calling it is a wiring bug, not a runtime condition.