Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

This was an excellent approach from PydanticAI, got adopted by hosted agents and other protocols too. I see in forums lot of developers find it useful. Caveat is that LLMs have become better, so they can possibly work with unstructured results or there can be specialized transformation abstractions that clients can integrated which offload this work from agent developers. Would be great to get feedback on all of these dimensions.

Abstract

This proposal outlines a mechanism to enable MCP clients to request structured outputs from tool calls, allowing the client to specify a desired response format (such as JSON with a specific schema). By supporting structured outputs, MCP can better serve developer use cases requiring machine-processable responses, particularly for agentic workflows and application integrations.

Motivation

Current MCP tool responses are primarily designed for human readability, returning free-form text that requires additional parsing to extract structured data. This approach creates several challenges:

1. Unpredictable response formats: Clients must implement custom parsing logic for each server and tool
2. Fragile data extraction: Extracting structured data from text responses is error-prone
3. Limited machine-processability: Free-form text responses reduce automation potential

Many MCP use cases involve integrating tools into workflows that require structured data processing. By allowing clients to request specific output formats, we can improve developer experience and enable more robust integrations.

Proposal Details

We propose extending the tools/call request to include a schema specification that indicates the client's suggested response format.

Changes to Request Schema

export interface Request {
    // Existing fields
    _meta?: {
        /**
        * The desired output format specification
        */
        suggestedFormat?: {
            /**
            * MIME type of the suggested response (e.g., "application/json")
            */
            mimeType: string;
            /**
            * JSON Schema defining the suggested structure (for JSON responses)
            */
            schema?: object;
        }
    };
}

Response Format

The server would return a response conforming to the requested format whenever possible:

export interface Result {
  _meta?: {
    /**
     * Indicates whether the response conforms to the requested format
     */
    suggestedFormatApplied?: boolean;
  };
}

For JSON responses, the formatted content would be provided as a valid JSON string within a TextContent object of CallToolResult:

{
  "type": "text",
  "text": "[{\"id\":\"item1\",\"name\":\"Example 1\"},{\"id\":\"item2\",\"name\":\"Example 2\"}]"
}

Extend tool annotation

Extend tool annotations to hint if it supports formatting.

export interface ToolAnnotations {
  // Existing fields
  formattingHint?: boolean;
}

Request Flow Examples

# REQUEST
{
    "id": 1,
    "method": "tools/call",
    "params": {
    "name": "list_tickets",
    "arguments": {
        "status": "open"
    },
    "_meta": {
        "suggestedFormat": {
            "mimeType": "application/json",
            "schema": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "ticketNumber": { "type": "string" },
                        "description": { "type": "string" }
                    },
                    "required": ["ticketNumber", "description"]
                }
            }
        }
    }
}

# RESULT
{
    "id": 1,
    "result": {
    "content": [
        {
            "type": "text",
            "text": "[{\"ticketNumber\":\"REQ12312\",\"description\":\"request for VPN access\"},{\"ticketNumber\":\"REQ23422\",\"description\":\"Add to DL - team-gcp-onboarding\"}]"
        }
    ],
    "_meta": {
        "suggestedFormatApplied": true
    }
}

Server Behavior

Servers implementing this proposal should:

1. Parse the suggestedFormat field in requests when present
2. Attempt to generate responses conforming to the specified format and schema
3. Return the formatted data as text content with proper escaping
4. Include formatApplied: true in metadata when successfully meeting format requirements
5. Fall back to default output formats when unable to meet the requested format

Client Behavior

Clients using this feature should:

1. Include suggestedFormat metadata when structured responses are desired
2. Provide accurate schemas for JSON responses
3. Check the formatApplied flag to determine if parsing is necessary
4. Handle both formatted and unformatted responses gracefully

Backward Compatibility

This proposal maintains full backward compatibility:

1. The suggestedFormat field is optional
2. Existing servers will ignore the metadata
3. Existing clients can continue to work with servers that implement this proposal

Alternatives

1. Separate field for structured response: We can introduce a separate field in result to capture structured response. Advantage of doing this is not clear yet, but its a two way door to extend to add another field in response in future.

References

1. MCP Agents Discussion: Improvements for MCP-based agents #111
2. JSON Schema Specification: https://json-schema.org/specification
3. Model Context Protocol Schema: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.ts

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other