SEP-2633: Standard Client-Side Configuration Format - mcp.json by BobDickinson · Pull Request #2633 · modelcontextprotocol/modelcontextprotocol

BobDickinson · 2026-04-22T21:43:43Z

The MCP ecosystem has server.json (the MCP Registry package specification), and soon the related ServerCard, for describing how servers can be configured. But there's no standard for the other side: how a client will connect to its servers.

Today every MCP client invents its own format for server configuration. Clients use different file names, and even different file types (JSON, JSONC, and TOML). They use different top-level keys (including "servers" and "mcpServers"). They use different values for the type field. They use different mechanisms and encodings for secret interpolation. The list goes on. This makes it hard to share MCP server configurations across clients.

mcp.json is a proposal for a minimal, client-side configuration format that any MCP client can adopt, and that will provide interoperability of MCP server configurations across clients.

Note: Initial draft is opinionated with many decisions made by the author. These decisions should be considered a starting point for discussion.

tadasant

High level thought: we should probably propose this as an Extension instead of straight to core (that is likely the direction Server Card is going as well).

tadasant · 2026-04-27T16:05:12Z

+
+## Abstract
+
+The MCP ecosystem has server.json (the MCP Registry package specification), and soon the related ServerCard, for describing how servers can be configured. But there's no standard for the other side: how a client will connect to its servers.


Suggested change

The MCP ecosystem has server.json (the MCP Registry package specification), and soon the related ServerCard, for describing how servers can be configured. But there's no standard for the other side: how a client will connect to its servers.

The MCP ecosystem has [server.json](https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md) (the MCP Registry package specification), and soon the related [Server Card](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127), for describing how servers can be configured. But there's no standard for the other side: how a client will connect to its servers.

tadasant · 2026-04-27T16:09:21Z

+
+```json
+{
+  "mcpServers": {


Do we definitely want/need to define mcpServers like this?

Could we potentially scope this spec down to be "the object you put inside mcpServers"; implying the choice of e.g. mcpServers vs. servers is up to the client?

Maybe that's confusing, because then we're not really replacing what is commonly today called the .mcp.json file, we're more just replacing the object in the mcpServers field... but that also seems potentially cleaner, in that we're not trying to wholesale replace that whole file (what with e.g. VS Code's management of inputs, etc).

And maybe the design goal here is to define the whole file, so you can copy/paste the whole thing... probably don't feel strongly on this, but what do you think?

tadasant · 2026-04-27T16:11:33Z

+}
+```
+
+Server names must match `^[a-zA-Z0-9_\[\]-]+$` (alphanumeric, hyphens, underscores, brackets).


We should probably allow for name as defined in server.json, i.e. allow . and / as part of DNS prefixing. But of course this is a "localized" name that doesn't have to align with name.

tadasant · 2026-04-27T16:14:01Z

+}
+```
+
+#### streamable-http — HTTP Streaming


Suggested change

#### streamable-http — HTTP Streaming

#### streamable-http — Streamable HTTP

tadasant · 2026-04-27T16:14:11Z

+
+#### streamable-http — HTTP Streaming
+
+For remote servers using HTTP streaming:


Suggested change

For remote servers using HTTP streaming:

For remote servers using streamable HTTP:

tadasant · 2026-04-27T16:22:28Z

+
+| Scheme  | Description     | Example                       |
+| ------- | --------------- | ----------------------------- |
+| `env`   | Environment var | `env:ENV_VAR_NAME`            |


Should we still allow for the absence of a scheme to imply env, as is probably convention out there right now, or do you think that's a bad idea for some reason?

tadasant · 2026-04-27T16:30:08Z

+
+| Scheme  | Description     | Example                       |
+| ------- | --------------- | ----------------------------- |
+| `env`   | Environment var | `env:ENV_VAR_NAME`            |


Perhaps ironic given my ask about making this a default: but should we explicitly discourage usage of environment variables as secrets? Typical ways people inject environment variables (i.e. storing in a file and sourcing them) seems to be the pattern by which rogue agents can pick up tokens and make API calls they're not meant to have access to. And thus encouraging clients to support schemes like op might meaningfully nudge along MCP security posture.

Co-authored-by: Tadas Antanavicius <tadas@tadasant.com>

tobinsouth · 2026-05-19T03:51:48Z

looking at some real world use cases, I think the oauth object is a couple of fields short of being able to describe lots of real OAuth servers we see in the wild. three fields (clientId, scopes, redirectUri) covers the happy path — DCR + PKCE + working RFC 8414 discovery — but falls over on confidential clients, CIMD, broken discovery, and "register your own client."

I've written up the publisher-side half of this as a separate SEP — SEP-2742 (the menu shape that a Server Card / server.json would carry, what auth methods does a server support). Trying to keep the layering clean: server.json = the menu, mcp.json = the choice. The two PRs are meant to be read together.

The short version of what I think is missing here:

Confidential clients — there's no field for a client secret, private key, or mTLS cert. Server requires client_secret / private_key_jwt / tls_client_auth? Can't be configured. I'm pretty sure we support this in ext-auth.
CIMD — a clientId that's an https:// URL is ambiguous. Is it a Client ID Metadata Document or just a static ID that looks like a URL? The connect behavior is totally different and you can't tell from the JSON.
Broken discovery — the spec assumes .well-known/oauth-authorization-server works. A surprising number of real ASes don't publish it (Snowflake's Custom OAuth being a well-documented one). No escape hatch.
Auth posture — can't tell whether the server wants auth before initialize, accepts anon and 401s lazily (e.g., partial auth), or doesn't care.
$schema — no version field. Cheap to add now, very annoying to retrofit.
The serverCard ref open question — already flagged in the SEP, and I think it's the load-bearing one. Got a concrete proposal — happy to sketch it inline or in a follow-up.

First version

a7b8ee1

BobDickinson changed the title ~~SEP-0000: Standard Client-Side Configuration Format - mcp.json~~ SEP-2633: Standard Client-Side Configuration Format - mcp.json Apr 22, 2026

BobDickinson added 2 commits April 22, 2026 14:46

Added PR number to doc

b00a129

Renamed and updated with PR number

2cd4c4f

BobDickinson marked this pull request as draft April 22, 2026 21:48

BobDickinson added 2 commits April 22, 2026 14:53

Formatted with prettier

a247566

Ran generate:seps

e066c00

BobDickinson requested a review from tadasant April 22, 2026 21:59

tadasant reviewed Apr 27, 2026

View reviewed changes

Apply suggestion from @tadasant

6f10887

Co-authored-by: Tadas Antanavicius <tadas@tadasant.com>

tobinsouth mentioned this pull request May 19, 2026

SEP-2742: Declaring Authentication Methods for Remote MCP Servers #2742

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SEP-2633: Standard Client-Side Configuration Format - mcp.json#2633

SEP-2633: Standard Client-Side Configuration Format - mcp.json#2633
BobDickinson wants to merge 6 commits into
modelcontextprotocol:mainfrom
BobDickinson:sep/standard-client-mcp-json-configuration

BobDickinson commented Apr 22, 2026

Uh oh!

tadasant left a comment

Uh oh!

tadasant Apr 27, 2026

Uh oh!

tadasant Apr 27, 2026

Uh oh!

tadasant Apr 27, 2026

Uh oh!

tadasant Apr 27, 2026

Uh oh!

tadasant Apr 27, 2026

Uh oh!

Uh oh!

tadasant Apr 27, 2026

Uh oh!

Uh oh!

Uh oh!

tadasant Apr 27, 2026

Uh oh!

tobinsouth commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Abstract

		The MCP ecosystem has server.json (the MCP Registry package specification), and soon the related ServerCard, for describing how servers can be configured. But there's no standard for the other side: how a client will connect to its servers.

	#### streamable-http — HTTP Streaming
	#### streamable-http — Streamable HTTP


		#### streamable-http — HTTP Streaming

		For remote servers using HTTP streaming:

	For remote servers using HTTP streaming:
	For remote servers using streamable HTTP:

Conversation

BobDickinson commented Apr 22, 2026

Uh oh!

tadasant left a comment

Choose a reason for hiding this comment

Uh oh!

tadasant Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

tadasant Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

tadasant Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

tadasant Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

tadasant Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tadasant Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tadasant Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

tobinsouth commented May 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants