feat: Add MCP server configuration parsing (e.g.: `mcp.json`) to the SDK #968

msabramo · 2025-06-16T20:56:56Z

Goals

Add features to the Python SDK that enable Python MCP client applications to support common functionality for configuration and reduce annoying differences between applications
Hopefully, once the ideas are discussed and settled on, this can be ported to the TypeScript SDK, so that client applications in that ecosystem can benefit as well.
Add MCPServersConfig class for parsing MCP server configuration (e.g.: mcp.json) to the SDK
Support feature that user can specify full command in command and it will automatically be parsed into command and args (Cursor has this feature but I don't know if any other apps do)
Support the standard mcpServers key or the servers key, which VS Code uses
Support VS Code inputs key and associated string interpolation
Support stripping out // comments (JSONC) because a lot of VS Code examples online have these
Optionally support YAML for MCP server configuration (while still preserving support for the JSON format)
Added docs for all the above at https://github.com/msabramo/python-sdk/blob/config/docs/client-configuration.md

Related issues/discussions

Motivation and Context

Config API

Claude Desktop introduced the mcp.json file and then a lot of other applications copied the idea pretty closely, but some applications made little tweaks to their parsing code to support extensions. Examples:

Cursor allows one to put a full shell command into command for a stdio server which saves the user from having to split a shell command into a command string and args list, which is tedious.
Visual Studio Code GitHub Copilot uses servers key instead of mcpServers and supports an inputs key and allows associated interpolation of these inputs in other server fields (e.g.: https://github.com/Azure-Samples/remote-mcp-functions-python/blob/main/.vscode/mcp.json)

AFAIK, there is no standard for the mcp.json so various applications have been evolving it very informally and so applications have differing abilities and their config files aren't necessarily compatible with each other.

This PR aims to create a simple API that standardizes config parsing so applications don't need to worry about implementing it and users benefit from more consistency between its handling by applications.

from mcp.client.config.mcp_servers_config import MCPServersConfig

mcp_server = MCPServersConfig.from_file("~/.cursor/mcp.json").servers["time"]

print(f"Effective command: {mcp_server.effective_command}")
print(f"Effective args: {mcp_server.effective_args}")

Assuming that ~/.cursor/mcp.json has this:

{
  "mcpServers": {
    "time": {
      "command": "uvx mcp-server-time"
    },
    ...
}

(Note the above syntax of stuffing the entire command in command works in Cursor but I don't think it works in Claude Desktop)

then the output of this code is:

Effective command: uvx
Effective args: ['mcp-server-time']

Note that even though just command was specified, the code went ahead and parsed the command and split it into separate command and args so that the user doesn't have to.

Problems with JSON

The JSON format has some drawbacks:

No support for comments
No tolerance of commas at the end of a list, which leads to errors and noisy diffs

YAML MCP server config

Because of these problems with JSON, I have added an optional YAML variant of the server configuration. It provides a very nice, clean syntax for configuration for those who want to use it:

mcpServers:
  time:
    command: uvx mcp-server-time

  filesystem:
    command: npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop

If I have the above YAML in mcp.yaml and this Python code:

from mcp.client.config.mcp_servers_config import MCPServersConfig

mcp_config = MCPServersConfig.from_file("mcp.yaml")

filesystem_mcp_server = mcp_config.servers["filesystem"]

print(f"Effective command: {filesystem_mcp_server.effective_command}")
print(f"Effective args: {filesystem_mcp_server.effective_args}")

then the output is:

Effective command: npx
Effective args: ['-y', '@modelcontextprotocol/server-filesystem', '/Users/username/Desktop']

However, YAML is optional, and I have tried to ensure that existing mcp.json files work as expected with no changes.

This PR seeks to add parsing of the MCP servers configuration to the MCP SDK, so:

Applications have a stable base to rely on and don't have to duplicate work
Applications can get new configuration features more easily
MCP can evolve and it will be easier for applications to adapt to the changes

How Has This Been Tested?

Pretty extensive unit tests

Breaking Changes

No. There are lots of tests that use mcp.json files to ensure they are parsed correctly.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
https://github.com/msabramo/python-sdk/blob/config/docs/client-configuration.md

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed
https://github.com/msabramo/python-sdk/blob/config/docs/client-configuration.md

Additional context

Add the ability to parse a multi-word command and extract the command and args into `effective_command` and `effective_args` attributes.

More realistic

This reverts commit 38eff49.

instead of str.split, which breaks when there are quoted arguments with spaces in them.

msabramo · 2025-06-16T21:32:50Z

The failing tests appears to not be from my changes. From GitHub Copilot Explain Error:

Issue Analysis

The failing job (44209986832) encountered an AssertionError in the test file tests/issues/test_188_concurrency.py on line 38. The assertion assert duration < 6 * _sleep_time_seconds failed because the duration of executing concurrent tasks exceeded the expected time limit.

Problem

The test test_messages_are_executed_concurrently attempts to execute multiple tasks concurrently and expects their combined execution duration to be less than 6 * _sleep_time_seconds. However, the actual duration exceeded this limit, indicating potential issues such as:

Higher-than-expected latency in task execution.
Inefficient task scheduling or resource contention.

Solution

To address this:

Increase the allowed duration threshold:
If the current threshold is too strict based on system load or other factors, you can increase the multiplier in the assertion (e.g., change 6 * _sleep_time_seconds to a higher value).
Optimize task execution:
Ensure that tasks are properly scheduled to execute concurrently without resource contention. Review the create_connected_server_and_client_session function and confirm that the anyio.create_task_group() is correctly utilized.

Code Suggestions

Modify the Test

Increase the threshold to accommodate system variability:

assert duration < 10 * _sleep_time_seconds  # Adjust multiplier

Optimize Resource Handling in `create_connected_server_and_client_session`

Ensure the client_session initialization does not introduce delays:

async with anyio.create_task_group() as tg:
    tg.start_soon(
        lambda: server.run(
            server_read,
            server_write,
            server.create_initialization_options(),
            raise_exceptions=raise_exceptions,
        )
    )
    async with ClientSession(
        read_stream=client_read,
        write_stream=client_write,
        read_timeout_seconds=read_timeout_seconds,
        sampling_callback=sampling_callback,
        list_roots_callback=list_roots_callback,
        logging_callback=logging_callback,
        message_handler=message_handler,
        client_info=client_info,
    ) as client_session:
        await client_session.initialize()
        yield client_session  # Ensure proper yielding without blocking

Workflow Check

The .github/workflows/pull-request-checks.yml references a shared configuration (./.github/workflows/shared.yml). Ensure this workflow doesn't impose additional constraints affecting test execution.

Summary

Adjust test threshold (duration < 10 * _sleep_time_seconds).
Optimize session creation for minimal latency.
Review shared workflow configurations for potential bottlenecks.

Let me know if you need further assistance or adjustments!

I found these in a 5ire `mcp.json` config file

because I was seeing tests failing on Windows in GitHub Actions and GitHub Copilot [said](modelcontextprotocol#968 (comment))

It seemed weird doing it in `from_file`, because the caller has to call `from_file` to find out what the required inputs are and then has to call `from_file` against to provide the input values. Now, the caller calls config.get(server, input_values={...}) to provide the input values

dsp-ant · 2025-06-17T11:32:03Z

Letting @ihrpr chime in here, but I believe it would be better if this is an external package that people can use. Since mcp.json is not part of the MCP standard, I don't think we want to include it for now.

msabramo added 21 commits June 16, 2025 09:51

First cut at config API

7d20254

Add effective_command and effective_args

c92c12f

Add the ability to parse a multi-word command and extract the command and args into `effective_command` and `effective_args` attributes.

Make infer_server_types typed; fix warnings

444960c

test_explicit_types_are_respected

2bf423d

More descriptive server names in tests

8ce1221

test_streamable_http_server => test_streamable_http_server_with_headers

8dfa25b

Test refactoring

25b3a7b

Move test fixtures from Python to mcp.json

37a6bb0

More realistic

ruff format

7d63c26

Add JSONC support

38eff49

Revert "Add JSONC support" 8000

71adf90

This reverts commit 38eff49.

Add YAML support

68b1a2e

Use shlex.split to parse command

a707aeb

instead of str.split, which breaks when there are quoted arguments with spaces in them.

More YAML tests

729c0db

Handle multiline YAML commands with backslashes

651d504

Fix pre-commit failures

54d173e

ruff format tests/client/config/test_yaml_functionality.py

76ee90b

ruff format tests/client/config/__init__.py

e2e16f4

Remove unnecessary import json

8b3593c

Allow config_path: Path | str

f9d48d6

Allow config_path to use ~ for home dir

4af7fe4

Allow config_path: Path | str

f9d48d6

Allow config_path to use ~ for home dir

4af7fe4

Expand environment variables in config_path

6574cfc

msabramo changed the title ~~feat: Add MCP server configuration (e.g.: mcp.json) to the SDK~~ feat: Add MCP server configuration parsing (e.g.: mcp.json) to the SDK Jun 16, 2025

msabramo added 5 commits June 16, 2025 14:56

Add as_dict method

dd7a77d

Support both "servers" and "mcpServers" keys

66e0e0e

Support VS Code "inputs" key

8c8e657

Strip out // comments (JSONC support)

85036e0

Fix lint issues

27e5b12

msabramo force-pushed the config branch from 967b6c7 to 27e5b12 Compare June 16, 2025 22:42

msabramo added 7 commits June 16, 2025 15:49

Add tests for when yaml is not importable

70e91b9

Add support for name, description, isActive optional fields

cf2b2be

I found these in a 5ire `mcp.json` config file

8000
Smarter detection of SSE servers

6493c57

Lowercase fields before checking for "sse" in them

27c63e6

Remove as_dict method

d5aeca6

ruff format tests/client/config/test_mcp_servers_config.py

d6d3809

Add docs

fbfa594

msabramo added a commit to msabramo/python-sdk that referenced this pull request Jun 17, 2025

Allow longer duration in test_188_concurrency

0febc4c

because I was seeing tests failing on Windows in GitHub Actions and GitHub Copilot [said](modelcontextprotocol#968 (comment))

msabramo mentioned this pull request Jun 17, 2025

Allow longer duration in test_188_concurrency #969

Merged

9 tasks

msabramo added 8 commits June 16, 2025 17:36

Documentation tweaks

eec3c2b

Docs tweaks

31eb3e1

Docs tweaks

9753da8

Docs tweaks

02fc66f

Doc updates

71e20d1

Emit warning when servers attribute accessed

0c3bde3

Add tests/client/config/test_warning_functionality.py

1ac383e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Add MCP server configuration parsing (e.g.: `mcp.json`) to the SDK #968

feat: Add MCP server configuration parsing (e.g.: `mcp.json`) to the SDK #968

Uh oh!

Uh oh!

Uh oh!

Uh oh!

feat: Add MCP server configuration parsing (e.g.: mcp.json) to the SDK #968

Are you sure you want to change the base?

feat: Add MCP server configuration parsing (e.g.: mcp.json) to the SDK #968

Conversation

Uh oh!

Goals

Related issues/discussions

Motivation and Context

Config API

Problems with JSON

YAML MCP server config

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Uh oh!

Issue Analysis

Problem

Solution

Code Suggestions

Modify the Test

Optimize Resource Handling in create_connected_server_and_client_session

Workflow Check

Summary

Uh oh!

Uh oh!

Uh oh!

feat: Add MCP server configuration parsing (e.g.: `mcp.json`) to the SDK #968

feat: Add MCP server configuration parsing (e.g.: `mcp.json`) to the SDK #968

Optimize Resource Handling in `create_connected_server_and_client_session`