MCP Options

MCP Options

These options are used with WithMCP():

app.WithMCP(
    app.WithMCPTool("search", "Search products", handler,
        app.WithMCPStringInput("query", "Search text", app.MCPRequired()),
    ),
    app.WithMCPResource("products://catalog", "Catalog", "Full catalog", catalogHandler),
)

Server Options

WithMCP

func WithMCP(opts ...MCPOption) Option

Enables the business-facing MCP server and applies the given options. The server is mounted at /mcp by default.

WithMCPIf

func WithMCPIf(cond bool, opts ...MCPOption) Option

Conditionally enables the MCP server based on a boolean condition. When cond is false, the option is a no-op.

WithMCPPrefix

func WithMCPPrefix(prefix string) MCPOption

Sets the mount prefix for the MCP server.

Default: "/mcp"

Tool Registration

WithMCPTool

func WithMCPTool(name, description string, handler MCPToolHandler, inputs ...MCPInputOption) MCPOption

Registers a tool on the MCP server.

Validation at init:

• A nil handler produces a configuration error.
• A nil MCPInputOption or nil MCPParamOption produces a configuration error.
• Duplicate tool names produce a configuration error.
• An empty name or description produces a configuration error.

WithMCPResource

func WithMCPResource(uri, name, description string, handler MCPResourceHandler) MCPOption

Registers a resource on the MCP server.

A nil handler produces a configuration error at init.

Handler Types

MCPToolHandler

type MCPToolHandler func(ctx context.Context, args MCPToolArgs) (any, error)

Handler for tool invocations. Return any JSON-serializable value. If an error is returned, it is sent as a tool error result.

MCPResourceHandler

type MCPResourceHandler func(ctx context.Context) (any, error)

Handler for resource reads. Return any JSON-serializable value.

MCPToolArgs

Type-safe access to tool input arguments.

Constructor

func NewMCPToolArgs(args map[string]any) MCPToolArgs

Creates an MCPToolArgs from a raw argument map. Useful in tests to construct tool arguments without going through mcp-go.

Zero-Value Accessors

Return the zero value if the argument is missing or has the wrong type:

Required Accessors

Return an error if the argument is missing or has the wrong type:

Input Constructors

Six input types, aligned 1:1 with the MCP specification:

All constructors share the same signature:

func WithMCP<Type>Input(name, description string, opts ...MCPParamOption) MCPInputOption

MCPParamOption Modifiers

Full Applicability Table

Mismatched modifiers (e.g. MCPMinLength on a number) are silently ignored (consistent with mcp-go). However, nil options and nil handlers always produce a configuration error.

Endpoints Registered

The path changes when WithMCPPrefix is used.

Example

app.WithMCP(
    app.WithMCPPrefix("/api/mcp"),

    app.WithMCPTool("search_products", "Search the product catalog",
        func(ctx context.Context, args app.MCPToolArgs) (any, error) {
            query, _ := args.RequireString("query")
            return productService.Search(ctx, query)
        },
        app.WithMCPStringInput("query", "Search query", app.MCPRequired(), app.MCPMinLength(1)),
        app.WithMCPNumberInput("min_price", "Minimum price", app.MCPMinimum(0)),
        app.WithMCPIntegerInput("page", "Page number", app.MCPMinimum(1), app.MCPDefault(1.0)),
        app.WithMCPBooleanInput("in_stock", "Only in-stock", app.MCPDefault(false)),
    ),

    app.WithMCPResource("orders://recent", "Recent Orders",
        "The 10 most recently placed orders",
        func(ctx context.Context) (any, error) {
            return orderService.ListRecent(ctx, 10)
        },
    ),
)