MCP Options
3 minute read
MCP Options
These options are used with WithMCP():
type SearchInput struct {
Query string `json:"query" jsonschema:"Search query text,minLength=1"`
}
app.WithMCP(
app.WithMCPTool("search", "Search products",
func(ctx context.Context, input SearchInput) (any, error) {
return productService.Search(ctx, input.Query)
},
),
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[I any](name, description string, handler MCPToolHandler[I]) MCPOption
Registers a tool on the MCP server. The input schema is derived automatically from the I type’s json and jsonschema struct tags.
| Parameter | Type | Description |
|---|---|---|
name | string | Unique tool name (must be non-empty) |
description | string | Human-readable description shown to AI agents (must be non-empty) |
handler | MCPToolHandler[I] | Function called when the tool is invoked (must be non-nil) |
Validation at init:
- A nil
handlerproduces a configuration error. - Duplicate tool names produce a configuration error.
- An empty
nameproduces a configuration error.
WithMCPResource
func WithMCPResource(uri, name, description string, handler MCPResourceHandler) MCPOption
Registers a resource on the MCP server.
| Parameter | Type | Description |
|---|---|---|
uri | string | Resource URI (e.g. orders://recent) |
name | string | Human-readable resource name |
description | string | Description shown to AI agents |
handler | MCPResourceHandler | Function called when the resource is read (must be non-nil) |
A nil handler produces a configuration error at init.
Handler Types
MCPToolHandler
type MCPToolHandler[I any] func(ctx context.Context, input I) (any, error)
Handler for tool invocations. I is the input struct type — its fields define the tool’s input schema via json and jsonschema struct tags. 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.
Input Schema with Struct Tags
Tool inputs are defined as Go structs. Field names use json tags. Schema constraints use jsonschema tags.
Supported jsonschema Tag Directives
| Directive | Applies to | Example |
|---|---|---|
| (first value) | all | Description text: jsonschema:"Search query text" |
minLength=N | string | jsonschema:"...,minLength=1" |
maxLength=N | string | jsonschema:"...,maxLength=100" |
pattern=REGEX | string | jsonschema:"...,pattern=^P[0-9]+$" |
enum=VAL | string | jsonschema:"...,enum=a,enum=b,enum=c" |
minimum=N | number, integer | jsonschema:"...,minimum=0" |
maximum=N | number, integer | jsonschema:"...,maximum=1000" |
default=VAL | all | jsonschema:"...,default=1" |
Mark required fields with jsonschema:"required" when you need explicit required semantics.
Example Input Struct
type SearchInput struct {
Query string `json:"query" jsonschema:"Search query text,minLength=1"`
Category string `json:"category" jsonschema:"Product category filter,enum=electronics,enum=clothing,enum=books,enum=all"`
MinPrice float64 `json:"min_price" jsonschema:"Minimum price in USD,minimum=0"`
InStockOnly bool `json:"in_stock_only" jsonschema:"Only show in-stock items"`
Page int `json:"page" jsonschema:"Page number,minimum=1,default=1"`
}
Endpoints Registered
| Method | Path | Description |
|---|---|---|
GET | /mcp | MCP Streamable HTTP (listen for notifications) |
POST | /mcp | MCP Streamable HTTP (send requests) |
DELETE | /mcp | MCP Streamable HTTP (close session) |
The path changes when WithMCPPrefix is used.
Example
type SearchInput struct {
Query string `json:"query" jsonschema:"Search query,minLength=1"`
MinPrice float64 `json:"min_price" jsonschema:"Minimum price,minimum=0"`
Page int `json:"page" jsonschema:"Page number,minimum=1,default=1"`
InStock bool `json:"in_stock" jsonschema:"Only in-stock items"`
}
app.WithMCP(
app.WithMCPPrefix("/api/mcp"),
app.WithMCPTool("search_products", "Search the product catalog",
func(ctx context.Context, input SearchInput) (any, error) {
return productService.Search(ctx, input.Query, input.MinPrice, input.Page, input.InStock)
},
),
app.WithMCPResource("orders://recent", "Recent Orders",
"The 10 most recently placed orders",
func(ctx context.Context) (any, error) {
return orderService.ListRecent(ctx, 10)
},
),
)
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.