DRAFT: consider adding REST method annotations for things

[chughtapan]

SEP: REST Endpoint Type Hints for Resources

Title: REST Endpoint Type Hints for Resources
Author: Tapan Chugh (@chughtapan)
Status: Proposal
Type: Standards Track
Created: 2025-01-24

Abstract

This SEP proposes optional type hints for MCP resources to indicate REST endpoint semantics, including HTTP methods and request body schemas. These hints enable servers to expose existing REST APIs as MCP resources without requiring complete reimplementation, addressing the inefficiencies of current REST-to-MCP conversion approaches while maintaining full backward compatibility.

Motivation

Current approaches to exposing REST APIs through MCP face significant challenges:

1. Conversion Overhead: As noted in "Stop Converting Your REST APIs to MCP", auto-converting REST APIs to MCP tools creates context pollution, excessive token consumption, and overwhelms agents with too many endpoint choices.

2. Loss of Semantics: REST's HTTP method semantics (GET, POST, PUT, DELETE) are lost when converting to MCP's method-agnostic resources, requiring workarounds like encoding operations in URIs.

3. Reimplementation Burden: The vast amount of existing REST API code makes rewriting from scratch impractical. Resources provide a natural mapping to REST endpoints but currently lack the ability to express HTTP methods and request bodies.

4. Bootstrap Barrier: Developers need a way to quickly expose existing REST APIs for initial exploration and prototyping before investing in curated, agent-optimized interfaces.

This proposal addresses these issues by allowing resources to optionally declare REST semantics, enabling:

• Direct exposure of REST endpoints as resources
• Preservation of HTTP method semantics
• Structured request body collection via elicitation
• Gradual migration from REST to agent-optimized interfaces

Specification

This proposal extends the MCP specification with optional REST type hints for resources:

1. New Type Definition

/**
 * Schema for elicitation-style object structures.
 * Only allows flat objects with primitive-typed properties.
 */
export type ElicitationObjectSchema = {
  type: "object";
  properties: {
    [key: string]: PrimitiveSchemaDefinition;
  };
  required?: string[];
};

2. Extended Resource Annotations

/**
 * Extended annotations for resources that may represent REST endpoints.
 * All fields are optional to maintain backward compatibility.
 */
export interface ResourceAnnotations extends Annotations {
  /**
   * Optional hint about the HTTP method this resource supports.
   * When present, indicates this resource represents a REST endpoint.
   */
  httpMethod?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";

  /**
   * Optional schema for request body elicitation.
   * Used with POST, PUT, or PATCH methods to collect structured input from the user.
   * Uses the same schema format as elicitation requests.
   */
  requestBodySchema?: ElicitationObjectSchema;
}

3. Updated Resource Interfaces

The Resource and ResourceTemplate interfaces use ResourceAnnotations instead of the base Annotations type.

4. Elicitation Flow for REST Resources

When reading a resource with requestBodySchema:

1. Client sends resources/read request
2. Server initiates elicitation via elicitation/create to gather request body data
3. Client responds with user-provided values
4. Server performs the HTTP operation with the elicited data as the request body
5. Server returns the operation result as resource contents

Rationale

Design Decisions

1. Optional Annotations: All REST hints are optional to ensure 100% backward compatibility. Existing resources continue to work unchanged.

2. Reuse Elicitation: Rather than creating a new mechanism for request bodies, we reuse the existing elicitation system, maintaining consistency with the protocol.

3. Resources over Tools: While REST endpoints could be exposed as tools, resources provide better semantic alignment with REST's resource-oriented architecture and URI-based identification.

4. Limited Schema Complexity: Request body schemas use the same restricted format as elicitation (flat objects with primitive types) to maintain simplicity and ensure broad client support.

Alternatives Considered

1. Automatic Tool Generation: Current approaches like FastMCP convert REST endpoints to tools, but this loses REST semantics and creates the context pollution issues described in the motivation.

2. New Protocol Extension: A separate REST-specific protocol extension would add complexity without leveraging existing MCP concepts.

3. Complex Schemas: Supporting nested objects in request bodies was considered but would complicate implementation and diverge from existing elicitation patterns.

Backward Compatibility

This proposal maintains full backward compatibility:

• All new fields are optional
• Existing resources without REST hints continue to function normally
• Clients that don't understand REST hints can still read resources (though they won't perform REST operations)
• The elicitation flow is only triggered when requestBodySchema is present

Reference Implementation

A reference implementation would include:

1. Server-side: Extension of an existing MCP server to expose REST endpoints with appropriate annotations
2. Client-side: Extension of an MCP client to recognize REST hints and handle the elicitation flow
3. Example: A server exposing a simple REST API (e.g., a TODO list) as MCP resources

Security Implications

1. Authorization: Servers must ensure proper authorization for REST operations, especially for mutating methods (POST, PUT, DELETE)
2. Input Validation: Request body schemas provide basic validation, but servers must perform additional validation as with any API
3. CORS and Transport Security: When resources represent actual HTTP endpoints, standard web security practices apply

Examples

GET Resource

{
  "uri": "https://api.example.com/users/123",
  "name": "Get User",
  "mimeType": "application/json",
  "annotations": {
    "httpMethod": "GET"
  }
}

POST Resource with Request Body

{
  "uri": "https://api.example.com/users",
  "name": "Create User",
  "mimeType": "application/json",
  "annotations": {
    "httpMethod": "POST",
    "requestBodySchema": {
      "type": "object",
      "properties": {
        "name": { 
          "type": "string", 
          "description": "User's name" 
        },
        "email": { 
          "type": "string", 
          "format": "email",
          "description": "User's email address"
        }
      },
      "required": ["name", "email"]
    }
  }
}

Resource Template with REST Hints

{
  "uriTemplate": "https://api.example.com/users/{id}",
  "name": "Update User",
  "mimeType": "application/json",
  "annotations": {
    "httpMethod": "PUT",
    "requestBodySchema": {
      "type": "object",
      "properties": {
        "name": { 
          "type": "string", 
          "description": "Updated name" 
        },
        "email": { 
          "type": "string", 
          "format": "email",
          "description": "Updated email"
        }
      }
    }
  }
}

Conclusion

This proposal provides a pragmatic bridge between the existing REST API ecosystem and MCP, enabling developers to:

1. Quickly expose REST APIs for exploration and prototyping
2. Preserve REST semantics within MCP
3. Gradually migrate to more agent-optimized interfaces
4. Reduce the reimplementation burden

By making REST hints optional, we maintain MCP's flexibility while providing a clear path for REST API integration.