feat: Auto-detect transport type from config files #661

felixweinberger · 2025-07-30T15:38:57Z

Motivation and Context

When launching the inspector with --config, automatically set the transport
dropdown and server URL based on the config file contents. This eliminates
the need to manually switch between stdio/sse/streamable-http in the UI.

Use discriminated union for ServerConfig to properly type different transports
Detect transport type and URL from config, pass via query params
Maintain backwards compatibility for configs without explicit type field
Add comprehensive tests for the new functionality

Improves UX by making the config file the single source of truth for
server settings.

How Has This Been Tested?

Tested manually with different configs:

E.g. with a stdio based config:

// mcp_dev_config.json
{
    "mcpServers": {
        "default-server": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp[cli]",
                "mcp",
                "run",
                "/Users/fweinberger/path/to/my/code/stdio-test/main.py"
            ]
        }
    }
}

E.g. with a streamable-http based config:

// mcp_dev_config.json
{
    "mcpServers": {
        "default-server": {
            "type": "streamable-http",
            "url": "http://localhost:8000/mcp",
            "note": "For Streamable HTTP connections, add this URL directly in your MCP Client"
        }
    }
}

Breaking Changes

No.

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

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

Additional context

github-actions · 2025-07-30T15:40:52Z

🎭 Playwright E2E Test Results

✅ 24 passed

Details

24 tests across 3 suites
29.3 seconds
6831970
ℹ️ Test Environment: Ubuntu Latest, Node.js v22.17.1
Browsers: Chromium, Firefox

📊 View Detailed HTML Report (download artifacts)

cliffhall

Hey @felixweinberger, thanks for this!

There is a stalled PR that is working toward this. I'm mentioning it here so it can be closed if this one is merged. It is trying to modify client/bin/start.js though.
I'm testing this locally, and I realized start.js is not going to be the right place but cli.js is, since it's the entrypoint for the inspector package via npx. And placing this hook in cli.js, the common launching script, this should work with the CLI inspector as well, though I'm not certain that's the case. I saw you added tests in cli-tests and that gave me the impression it would be the case, but...
CLI tests are failing. Turns out the CLI tests are launching the web client. Those tests are meant to test the CLI client. they should just run and be done, without having to interact with the browser. Tests of launching the web client would be more appropriate in client/e2e where the Playwright tests happen and can run in CI.

I notice in your example mcp_dev_config.json you provide a default-server, so I tried that and found that you cannot launch with --config and fail to specify a server name. It feels like this should be possible if there is a default-server configured. Maybe the if not present on the command line, the script can grep the file for 'default-server' and if present in the file, use it as the server arg.

Verified that I could launch if I added a --server argument

richardkmichael · 2025-08-02T03:28:13Z

@cliffhall @felixweinberger

In #643 there is a setup for Playwright testing of the command line arguments using tag @cli and different web command: .. for startup.

I created that setup to write tests to catch the CLI options bug #649 . PR #664 fixes that bug.

Note the Playwright CLI tests PR is currently on top of the bug fix so that I could verify the tests caught the bug, but passed after the fix.

I think all of this should be ready for review, if it's helpful here.

I thought a full end-to-end test of entry-point CLI arguments to UI would be helpful as a catch-all since the Inspector is several components. (I had experience with Playwright from #582 to test more of the UI.). Tighter tests around just the CLI would be helpful too.

(I also noticed the other new "CLI tests" are not same CLI. 😂 )

When launching the inspector with --config, automatically set the transport dropdown and server URL based on the config file contents. This eliminates the need to manually switch between stdio/sse/streamable-http in the UI. - Use discriminated union for ServerConfig to properly type different transports - Detect transport type and URL from config, pass via query params - Maintain backwards compatibility for configs without explicit 'type' field - Add comprehensive tests for the new functionality Improves UX by making the config file the single source of truth for server settings. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>

- Add tests for config files with different transport types (stdio, sse, streamable-http) - Add test for backward compatibility with configs missing type field - Verify transport and serverUrl options are correctly parsed from config files - All 36 tests pass

Move transport configuration parsing to cli.js as suggested in PR review. The CLI entry point (cli.js) should handle config file parsing and pass parameters to start.js.

- Remove web client launch tests from CLI test suite - Add CLI-mode tests for SSE and streamable-http configs - Keep only tests that use --cli flag as intended

- Test that transport and serverUrl parameters are correctly passed via URL - Verify SSE and streamable-http transport types are handled - Test default STDIO behavior

- Auto-select server when --config is used without --server - Use 'default-server' if it exists in config - Use single server if only one is defined - Show helpful error if multiple servers exist without default - Add tests for all default-server scenarios

- Add examples for stdio, sse, and streamable-http transport types - Document automatic server selection behavior - Show how to use default-server in config files

- Pass URL as command for SSE/HTTP configs instead of empty string - Update runCli to pass transport type flag when needed - Update tests to expect connection errors for non-existent SSE/HTTP servers

felixweinberger · 2025-08-05T13:28:13Z

Hey @felixweinberger, thanks for this!

@cliffhall @felixweinberger

In #643 there is a setup for Playwright testing of the command line arguments using tag @cli and different web command: .. for startup.

Thanks for the reviews - I've updated the PR to:

Moved arg parsing implementation to cli.ts
Reorganized CLI tests to not have web UI based tests in cli-tests.js
Added a new set of playwright based e2e tests that check config is respected in the web UI
Added default-server support (if default-server exists or if there's only one server with any name in the config file)
Updated docs

cliffhall

@felixweinberger Tests are looking good now.

I still had a problem launching without specifying the server.

mcp.json

{
  "mcpServers" : {
	"default-server": {
	  "command": "node",
	  "args": [
		"/Users/cliffhall/Projects/mcp-c64/dist/server/index.js"
	  ]
	}
  }
}

node cli/build/cli.js --config mcp.json

Inspector fields

node cli/build/cli.js --config mcp.json --server default-server

Inspector fields

- Add --transport and --server-url support to client/bin/start.js - Pass transport configuration through server to client via /config endpoint - Update client App.tsx to use defaultTransport and defaultServerUrl from server - Ensure SSE and HTTP transport configs work properly from CLI

felixweinberger · 2025-08-06T16:01:44Z

@cliffhall thanks for taking a detailed look, good catch!

I used your mcp.json example to add another commit on top of this to properly pass through the args now managed by cli.js back to start.js:

Before	After

cliffhall

Hey @felixweinberger, the config file is working great on my machine now, and I'm going to do a proper review of the code momentarily, but would you mind adding mcp.json to the .gitignore and .prettierignore in this PR?

I am just realizing that I will have one present for testing, and I expect @olaservo and other maintainers and contributors will as well. We don't want anyone to accidentally commit their file. And running prettier-check (automatically part of running tests) fails locally because of my mcp.json, which is what triggered this suggestion.

Also, from the playwright tests, I tried this command line:

npx . --transport sse --server-url http://localhost:3000/sse

Inspector

README.md

- Add --transport option to command line parser - Support --transport stdio/sse/http flags - Convert 'http' to 'streamable-http' internally - Fix transport type conversion for CLI mode

Add --server-url option to CLI parser so the flag is properly recognized and passed through to the server process via the /config endpoint.

felixweinberger · 2025-08-07T11:16:41Z

Hey @felixweinberger, the config file is working great on my machine now, and I'm going to do a proper review of the code momentarily, but would you mind adding mcp.json to the .gitignore and .prettierignore in this PR?

I am just realizing that I will have one present for testing, and I expect @olaservo and other maintainers and contributors will as well. We don't want anyone to accidentally commit their file. And running prettier-check (automatically part of running tests) fails locally because of my mcp.json, which is what triggered this suggestion.

Also, from the playwright tests, I tried this command line:

npx . --transport sse --server-url http://localhost:3000/sse

Inspector

🤦 forgot to actually parse --server-url in the cli.ts - amended. Also added mcp.json to .gitignore and .prettierignore as requested.

Tested with multiple different combinations:

npx . -> just opens last

npx . --config mcp.json -> works as expected for stdio, sse, http

npx . --transport sse --server-url http://localhost:3000/sse -> works

npx . --transport http --server-url http://localhost:4321/mcp -> works

npx . --transport stdio python main.py -> works

ochafik

Thanks Felix!

cli/src/cli.ts

client/bin/start.js

cliffhall

@felixweinberger thanks for handling those things. It's all looking good to me so far. I see @ochafik has a few requests, but I'm onboard to approve as soon as that's settled. Also, I think you're inheriting the manual args parsing stuff from the original cli.ts author, and if you want to punt that to another PR, it would fully make sense; it could be a bigger can of worms than you bargained for in this PR.

@ochafik

Only auto-select when there's exactly one server in the config file. Removes special handling for "default-server" naming convention. Addresses review feedback from @ochafik on PR #661

Test 30 now expects an error when multiple servers exist, even with "default-server" present, aligning with the simplified logic that only auto-selects when there's exactly one server.

cliffhall

LGTM! 👍

ochafik

Thanks!

felixweinberger force-pushed the fweinberger/better-config-support branch 6 times, most recently from f2dfe50 to 50b96a0 Compare July 30, 2025 18:55

felixweinberger marked this pull request as ready for review July 30, 2025 19:11

felixweinberger requested review from cliffhall and ochafik July 30, 2025 19:11

cliffhall requested changes Aug 1, 2025

View reviewed changes

felixweinberger mentioned this pull request Aug 5, 2025

bugfix: fix npx @modelcontextprotoco/inspector failing on main #681

Merged

3 tasks

felixweinberger force-pushed the fweinberger/better-config-support branch from 50b96a0 to 9d8c2ec Compare August 5, 2025 11:12

felixweinberger changed the base branch from main to fweinberger/fix-npx-no-args August 5, 2025 11:12

Base automatically changed from fweinberger/fix-npx-no-args to main August 5, 2025 12:14

felixweinberger and others added 8 commits August 5, 2025 14:08

Remove transport/serverUrl parsing from start.js

b6dc2ce

Move transport configuration parsing to cli.js as suggested in PR review. The CLI entry point (cli.js) should handle config file parsing and pass parameters to start.js.

Clean up CLI tests and add config parsing tests

63193ec

- Remove web client launch tests from CLI test suite - Add CLI-mode tests for SSE and streamable-http configs - Keep only tests that use --cli flag as intended

Add Playwright e2e tests for CLI argument handling

a7675d1

- Test that transport and serverUrl parameters are correctly passed via URL - Verify SSE and streamable-http transport types are handled - Test default STDIO behavior

Document transport types and default-server functionality

3a4f3bc

- Add examples for stdio, sse, and streamable-http transport types - Document automatic server selection behavior - Show how to use default-server in config files

prettier

1e399b7

felixweinberger force-pushed the fweinberger/better-config-support branch from d175c34 to 1e399b7 Compare August 5, 2025 13:09

Fix CLI test failures for SSE/HTTP transport configs

195f790

- Pass URL as command for SSE/HTTP configs instead of empty string - Update runCli to pass transport type flag when needed - Update tests to expect connection errors for non-existent SSE/HTTP servers

felixweinberger force-pushed the fweinberger/better-config-support branch from c288e03 to 195f790 Compare August 5, 2025 13:22

felixweinberger requested a review from cliffhall August 5, 2025 13:28

cliffhall requested changes Aug 5, 2025

View reviewed changes

felixweinberger requested a review from cliffhall August 6, 2025 16:06

cliffhall requested changes Aug 6, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

felixweinberger added 4 commits August 6, 2025 19:50

Add --transport flag support to CLI

98b7e63

- Add --transport option to command line parser - Support --transport stdio/sse/http flags - Convert 'http' to 'streamable-http' internally - Fix transport type conversion for CLI mode

ignore: ignore mcp.json as a common dev file

e1e702f

Fix --server-url flag not being parsed by CLI

cf7c138

Add --server-url option to CLI parser so the flag is properly recognized and passed through to the server process via the /config endpoint.

prettier

14b0181

felixweinberger requested a review from cliffhall August 7, 2025 11:07

ochafik requested changes Aug 7, 2025

View reviewed changes

cli/src/cli.ts Outdated Show resolved Hide resolved

cli/src/cli.ts Show resolved Hide resolved

client/bin/start.js Show resolved Hide resolved

cliffhall reviewed Aug 7, 2025

View reviewed changes

felixweinberger added 2 commits August 7, 2025 20:45

Simplify server auto-selection logic

1263ffd

Only auto-select when there's exactly one server in the config file. Removes special handling for "default-server" naming convention. Addresses review feedback from @ochafik on PR #661

Update test to match new server selection behavior

6831970

Test 30 now expects an error when multiple servers exist, even with "default-server" present, aligning with the simplified logic that only auto-selects when there's exactly one server.

felixweinberger requested a review from ochafik August 7, 2025 20:21

cliffhall approved these changes Aug 7, 2025

View reviewed changes

felixweinberger enabled auto-merge August 7, 2025 20:41

ochafik approved these changes Aug 8, 2025

View reviewed changes

felixweinberger merged commit 7b3e2c1 into main Aug 8, 2025
12 checks passed

felixweinberger deleted the fweinberger/better-config-support branch August 8, 2025 08:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Auto-detect transport type from config files #661

feat: Auto-detect transport type from config files #661

Uh oh!

felixweinberger commented Jul 30, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 30, 2025 •

edited

Loading

Uh oh!

cliffhall left a comment •

edited

Loading

Uh oh!

richardkmichael commented Aug 2, 2025 •

edited

Loading

Uh oh!

felixweinberger commented Aug 5, 2025

Uh oh!

cliffhall left a comment •

edited

Loading

Uh oh!

felixweinberger commented Aug 6, 2025 •

edited

Loading

Uh oh!

cliffhall left a comment •

edited

Loading

Uh oh!

Uh oh!

felixweinberger commented Aug 7, 2025 •

edited

Loading

Uh oh!

ochafik left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cliffhall left a comment •

edited

Loading

Uh oh!

cliffhall left a comment

Uh oh!

ochafik left a comment

Uh oh!

Uh oh!

Uh oh!

feat: Auto-detect transport type from config files #661

feat: Auto-detect transport type from config files #661

Uh oh!

Conversation

felixweinberger commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

github-actions bot commented Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎭 Playwright E2E Test Results

Details

Uh oh!

cliffhall left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richardkmichael commented Aug 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger commented Aug 5, 2025

Uh oh!

cliffhall left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixweinberger commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cliffhall left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

felixweinberger commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cliffhall left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cliffhall left a comment

Choose a reason for hiding this comment

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

felixweinberger commented Jul 30, 2025 •

edited

Loading

github-actions bot commented Jul 30, 2025 •

edited

Loading

cliffhall left a comment •

edited

Loading

richardkmichael commented Aug 2, 2025 •

edited

Loading

cliffhall left a comment •

edited

Loading

felixweinberger commented Aug 6, 2025 •

edited

Loading

cliffhall left a comment •

edited

Loading

felixweinberger commented Aug 7, 2025 •

edited

Loading

cliffhall left a comment •

edited

Loading