structured_input_and_output

Structured Content Example

This example shows how to return structuredContent in tool result with corresponding OutputSchema.

Defined in the MCP spec here: https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content

Usage

Define a struct for your input:

type WeatherRequest struct {
    Location string `json:"location" jsonschema:"City or location"`
    Units    string `json:"units,omitempty" jsonschema:"celsius or fahrenheit"`
}

A field is required unless its json tag contains omitempty (or omitzero). Here location is required and units is optional. The jsonschema tag value is used as the property description.

Define a struct for your output:

type WeatherResponse struct {
    Location    string  `json:"location" jsonschema:"The location"`
    Temperature float64 `json:"temperature" jsonschema:"Current temperature"`
    Conditions  string  `json:"conditions" jsonschema:"Weather conditions"`
}

Add it to your tool:

tool := mcp.NewTool("get_weather",
    mcp.WithDescription("Get weather information"),
    mcp.WithInputSchema[WeatherRequest](),
    mcp.WithOutputSchema[WeatherResponse](),
)

Return structured data in tool result:

func weatherHandler(ctx context.Context, request mcp.CallToolRequest, args WeatherRequest) (*mcp.CallToolResult, error) {
    response := WeatherResponse{
        Location:    args.Location,
        Temperature: 25.0,
        Conditions:  "Cloudy",
    }
    
    fallbackText := fmt.Sprintf("Weather in %s: %.1f°C, %s", 
        response.Location, response.Temperature, response.Conditions)
    
    return mcp.NewToolResultStructured(response, fallbackText), nil
}

Struct tag reference

Schemas are generated by google/jsonschema-go. The tags below reflect its current behavior:

• Description: use jsonschema:"some text". The older jsonschema_description:"..." tag is not read and is silently ignored.
• Required: derived automatically — a field is required unless its json tag contains omitempty or omitzero. There is no json:"...,required" option, and the jsonschema:"required" tag is no longer supported.
• Constraints (enum, minimum, maximum, ...): not supported as struct tags. A jsonschema tag value that begins with word= is rejected with tag must not begin with 'WORD='. To add constraints, use mcp.WithRawInputSchema() or the builder API (mcp.WithString, mcp.WithNumber, ... with options like mcp.Enum(...)).

See main.go for more examples.