[DOCS] TypeScript SDK documentation incomplete for `mcpServers` configuration - missing file path support

Resolved 💬 2 comments Opened Jan 23, 2026 by coygeek Closed Feb 28, 2026

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://docs.anthropic.com/en/agent-sdk/typescript#claudeagentoptions

Section/Topic

The ClaudeAgentOptions reference table, specifically the mcpServers property row.

Current Documentation

TypeScript SDK (typescript.md line 118):

| `mcpServers` | `Record<string, McpServerConfig>` | `{}` | MCP server configurations |

Python SDK (python.md line 495) for comparison:

| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path`  | `{}`  | MCP server configurations or path to config file |

What's Wrong or Missing?

The Python SDK documentation explicitly shows that mcp_servers accepts three types:

A dictionary of server configurations
A string (file path)
A Path object

The description clarifies: "MCP server configurations or path to config file"

The TypeScript SDK documentation only shows Record<string, McpServerConfig> with no mention of file path support. This creates ambiguity:

If TypeScript SDK does support passing a file path string, the documentation is incomplete
If TypeScript SDK does not support file paths, this is a feature parity gap that should be explicitly noted

The MCP documentation (mcp.md) mentions that .mcp.json config files are loaded automatically, but doesn't clarify whether the mcpServers option itself can accept a file path directly like Python's mcp_servers can.

Suggested Improvement

Option A (if TypeScript supports file paths):
Update the TypeScript SDK documentation to match Python:

| `mcpServers` | `Record<string, McpServerConfig> \| string` | `{}` | MCP server configurations or path to config file |

Option B (if TypeScript does not support file paths):
Add a note clarifying the difference:

| `mcpServers` | `Record<string, McpServerConfig>` | `{}` | MCP server configurations. Note: Unlike Python SDK, file paths are not supported; use `.mcp.json` for file-based configuration |

Impact

High - Prevents users from using a feature

Additional Context

Affected Files

| File | Line | Issue |
|------|------|-------|
| platform-claude/docs/en/agent-sdk/typescript.md | 118 | Missing string union type and "or path to config file" description |

Comparison Evidence

Python SDK (python.md lines 459, 495):

mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)

Description: "MCP server configurations or path to config file"