break: dramatically simplify interface, add tool name prefixes

[benjamincburns]

Description

Dramatically simplifies the interface of this library.

Removes features that should be implemented at the application level, like config file loading. The (now removed) default config file loading was especially problematic, as it's unexpected that a library like this would attempt to access the filesystem, especially on construction.

The former connectToServerViaX methods were especially confusing, as they were instance methods that would overwrite any existing connection config without closing, etc.

Also includes related test clean-up, README and examples changes, and a few project config changes that bring this more in line with how packages in the langchainjs monorepo are managed/configured.

Type of change

• 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 not work as expected)
• Documentation update
• Refactoring (no functional changes)

How Has This Been Tested?

Via the included test suite.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[vbarda]

should this be opt-in? not sure if i want this if i have only one server

[vbarda]

there was also a discussion on this briefly in py langchain-ai/langchain-mcp-adapters#18

it's probably good to add this as an option!

[benjamincburns]

yeah, good point - I was mostly just following the convention that I saw in claude code (it always prefixes MCP tools this way by default)

[benjamincburns]

Made this default to opt-in rather than opt-out.

[benjamincburns]

So actually, I think this should default to opt-in for direct use of loadMcpTools and opt-out for MultiServerMcpClient, as the latter case is more likely to benefit from differentiation of tools by server namespace

[CuriouslyCory]

Feedback, not criticism: It seems like every other tool takes an mcp.json config, and they're all the same format. Whether or not it is stored in a .json file doesn't matter to me, but being able to go to a tool like smithery.ai and grab the json config so I don't have to try and infer the implementation details is going to open up the usability to a lot more developers.

The new API does look much easier to grok. Coming in fresh to MCP the main hurdle at this point would be knowing what transport to use. Other tools don't seem to need to have it explicitly defined. Are there technical limitations preventing that, or just a matter of having the time?

[benjamincburns]

Massively appreciated feedback, @CuriouslyCory!

I think you've touched on two important things here.

1. Regardless of whether we tackle file I/O in this lib and config file parsing, the structure of our config object should align closely (likely so closely as to be a strict superset) with the emerging standard that we're seeing other tooling across the industry following (the MCP config schema used by Claude, Claude Code, Cusor, etc).

2. The user should be familiar with that format, but they shouldn't need to be familiar with the underlying technical details of the transports.

Based on this, I think a simple resolution to this feedback would be to get rid of the discriminator key in our Connection types (the types that ultimately define the config schema for connections to individual servers) and instead discriminate these types based on their underlying structure (e.g. the StdioConnection has a command field, while the SSEConnection does not).

I'll definitely take this opportunity to act on that - it's good feedback for sure! Please don't hesitate if you have more of it in the future - I wish we had a thousand more engaged users who would be this proactive!

[benjamincburns]

I think a simple resolution to this feedback would be to get rid of the discriminator key in our Connection types (the types that ultimately define the config schema for connections to individual servers) and instead discriminate these types based on their underlying structure (e.g. the StdioConnection has a command field, while the SSEConnection does not).

Unfortunately there doesn't seem to be any authoritative source for the emerging config "standard."

I did some experiments with the claude mcp add-json command from claude code. It seems like the connection schema is discriminated on a type field. That is, claude mcp add-json foo '{ "url": "http://example.com" }' fails with an error saying that command is a required field, but claude mcp add-json foo '{ "type": "sse", "url": "http://example.com" }' succeeds.

I'm also seeing some cases where the discriminator is required as transport, and others where it's not required at all. I've gone with the "be permissive in what you accept" approach and made it so we can accept any of these.