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 <[email protected]>

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.

addiplus · 2026-07-10T22:51:36Z

A data point from the stdio side. With Server Card now card-only (experimental-ext-server-card#28), the npm + stdio install path is the piece without a worked answer in the spec (issue #2963 landed here for that reason), and from what I can see that answer is nearly there already.

I maintain a small stdio server that's live in the registry (io.github.addiplus/vercel-deployment-mcp, v0.1.0). Its server.json declares the npm package with a stdio transport [1] and its env vars with isRequired/isSecret [2]. From those two blocks the client config is almost entirely derivable — everything but the runtime convention:

{
  "command": "npx",
  "args": ["-y", "@addiplus/[email protected]"],
  "env": { "VERCEL_TOKEN": "<prompt the user; declared isSecret>" }
}

That config works today against the published package, and the optional VERCEL_TEAM_ID drops out because it's isRequired: false; the mapping is field-sensitive, not a hardcoded template. The npx choice is the undeclared part, which is exactly what a written mapping would pin down. What can't be derived at all (integrity digests, consent text, re-approval policy — what HarperZ9 raised on #2963) reads like requirements for this SEP rather than registry schema changes. Registry PR #1364 (postInstallInstructions) fits the same split: the registry describes, the client derives.

So a concrete suggestion: include the npm+stdio mapping as a worked conformance example (registry entry in, mcp.json out), and let that example define which server.json fields are load-bearing for install. It would also help registry#749, which is parked pending this kind of standardization. Happy for this server.json to be the example's input if that saves anyone time; its config handling is pinned by tests at the tag [3]. Want me to draft that example section?

[1] https://github.com/addiplus/vercel-deployment-mcp/blob/v0.1.0/server.json#L11-L19
[2] https://github.com/addiplus/vercel-deployment-mcp/blob/v0.1.0/server.json#L20-L32
[3] https://github.com/addiplus/vercel-deployment-mcp/blob/v0.1.0/test/tools.test.ts#L365-L383

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 <[email protected]>

tobinsouth mentioned this pull request May 19, 2026

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

Open

This was referenced Jul 2, 2026

Proposal: Update urn:air schema to prefix air-type before publisher Agent-Card/ai-catalog#59

Open

Clarify whether server.json / Server Card should standardize stdio package install manifests #2963

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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!

addiplus commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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:

Uh oh!

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!

addiplus commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants