[DOCS] Inconsistent MCP Server `type` configuration between Messages API and Agent SDK

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#mcp-server-configuration - https://platform.claude.com/docs/en/agent-sdk/mcp#httpssse-servers

Section/Topic

The MCP Server configuration sections for both the direct Messages API (MCP connector) and the Agent SDK. specifically regarding the type field definition for remote servers.

Current Documentation

In the MCP Connector (API) documentation (https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#field-descriptions):

Property: type Description: Currently only "url" is supported

In the Agent SDK documentation (https://platform.claude.com/docs/en/agent-sdk/mcp#httpssse-servers):

mcpServers: {
  "remote-api": {
    type: "sse", // or "http"
    url: "https://api.example.com/mcp/sse",
    // ...
  }
}

What's Wrong or Missing?

There is a schema conflict between how the direct Messages API expects MCP servers to be defined and how the Agent SDK expects them to be defined.

1. The Messages API strictly requires type: "url".
2. The Agent SDK requires type: "sse" or type: "http".

This is confusing for developers who may be prototyping with the API and moving to the SDK (or vice-versa), as copying the configuration object from one environment to the other will result in validation errors or connection failures. The documentation does not acknowledge this difference, making it look like a potential inconsistency or typo.

Suggested Improvement

The Agent SDK documentation (https://platform.claude.com/docs/en/agent-sdk/mcp) should include a callout or note clarifying that the SDK's configuration schema differs from the direct Messages API schema.

Suggested text for Agent SDK docs:

Note: The Agent SDK uses type: "sse" or type: "http" for remote connections. This differs from the direct Messages API MCP Connector, which uses type: "url". Please ensure you use the correct type string for the SDK.

Impact

High - Prevents users from using a feature

Additional Context

The Python SDK source code confirms that McpSSEServerConfig explicitly types the literal as "sse" and McpHttpServerConfig as "http", whereas the API documentation explicitly states only "url" is supported. This confirms it is a structural difference in the implementations, not just a documentation error, but the documentation needs to bridge this gap to prevent developer confusion.