Define a Standard MCP Configuration Schema

[jlandowner]

Is your feature request related to a problem? Please describe.
I'm developing an MCP host. Existing MCP hosts read their configuration from a config JSON file, but I couldn’t find a standard configuration schema.

Currently, each implementation appears to handle configuration independently in some popular projects/products. There are concerns with this situation from multiple perspectives:

From the MCP host implementer's perspective:
Each implementation has its own design and validation mechanism. As new requirements—such as additional validation rules or authentication methods—arise, implementers must address these changes on a case-by-case basis. This fragmentation increases maintenance overhead and complicates keeping up with evolving specifications.

From the end-user's perspective:
Configuration options differ across products. Users must consult various product documents to understand each specific implementation's requirements, and if multiple products are used, configurations may vary (with different setting names). This inconsistency negatively impacts the user experience.

Here are some implementations in popular projects/products:

• Claude Desktop:
  [Quickstart for Claude Desktop](https://modelcontextprotocol.io/quickstart/user)
  Example configuration locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/Users/username/Desktop",
          "/Users/username/Downloads"
        ]
      }
    }
  }

  This configuration is minimal but no documentation for transport types like stdin or sse.

• VSCode's GitHub Copilot:
  [MCP Servers Documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server)

  {
    // 💡 Inputs are prompted on first server start, then stored securely by VS Code.
    "inputs": [
      {
        "type": "promptString",
        "id": "perplexity-key",
        "description": "Perplexity API Key",
        "password": true
      }
    ],
    "servers": {
      // https://github.com/ppl-ai/modelcontextprotocol/
      "Perplexity": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-perplexity-ask"],
        "env": {
          "PERPLEXITY_API_KEY": "${input:perplexity-key}"
        }
      }
    }
  }

  The inputs field is more advanced—it defines how to obtain authentication information and pass it to the command. Also, GitHub Copilot can read claude_desktop_config.json:

  VS Code can automatically detect and reuse MCP servers defined in other tools, such as Claude Desktop. Enable auto-discovery with the chat.mcp.discovery.enabled setting.

• Cline:
  The schema is defined using Zod.
  [Cline's MCP Schema in McpHub.ts](https://github.com/cline/cline/blob/807a4b36dfe14a18a3e6a0dc39e05594e2fbff4c/src/services/mcp/McpHub.ts#L48-L72)

  const AutoApproveSchema = z.array(z.string()).default([])
  
  const BaseConfigSchema = z.object({
  	autoApprove: AutoApproveSchema.optional(),
  	disabled: z.boolean().optional(),
  	timeout: z.number().min(MIN_MCP_TIMEOUT_SECONDS).optional().default(DEFAULT_MCP_TIMEOUT_SECONDS),
  })
  
  const SseConfigSchema = BaseConfigSchema.extend({
  	url: z.string().url(),
  }).transform((config) => ({
  	...config,
  	transportType: "sse" as const,
  }))
  
  const StdioConfigSchema = BaseConfigSchema.extend({
  	command: z.string(),
  	args: z.array(z.string()).optional(),
  	env: z.record(z.string()).optional(),
  }).transform((config) => ({
  	...config,
  	transportType: "stdio" as const,
  }))
  
  const ServerConfigSchema = z.union([StdioConfigSchema, SseConfigSchema])
  
  const McpSettingsSchema = z.object({
  	mcpServers: z.record(ServerConfigSchema),
  })

  Cline extends the schema with additional properties like autoApprove and disabled. It uses transportType to indicate whether the configuration is for stdin or sse, whereas GitHub Copilot uses a property called type.

• Continue:
  [Continue MCP Documentation](https://docs.continue.dev/customize/deep-dives/mcp)

  {
    "experimental": {
      "modelContextProtocolServers": [
        {
          "transport": {
            "type": "stdio",
            "command": "uvx",
            "args": ["mcp-server-sqlite", "--db-path", "/Users/NAME/test.db"]
          }
        }
      ]
    }
  }

Describe the solution you'd like
Define a standard MCP configuration schema. I propose using JSON Schema because it is language-independent and is already employed in MCP (e.g., in the ListTools response).

Here is an example of a server schema.

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": ["stdio", "sse"]
    },
    "command": {
      "type": "string"
    },
    "args": {
      "type": "array",
      "items": { "type": "string" }
    },
    "env": {
      "type": "object",
      "additionalProperties": { "type": "string" }
    },
    "url": {
      "type": "string",
      "format": "uri"
    }
  }
}

While this is merely a basic schema common to all current implementations, defining it could provide a base for future enhancements such as various authentication methods and other transport-specific configurations(e.g. the input field in GitHub Copilot)

Describe alternatives you've considered

[LucaButBoring]

Adding another reference point: LibreChat uses a similarish YAML config to Claude Desktop (example). Bringing it up here as it's notably not JSON; YAML is a superset of JSON but just showing that clients may not use the same config formats at all (Cline also uses JSON on-disk).

---

Different host applications will have different capabilities on different platforms, won't they? It would be useful for all stdio servers to share the same configuration schema, for example, but if someone (hypothetically) made a mobile app that only supported remote servers, it wouldn't be possible to have a compliant configuration file, since the application's capabilities would break the type contract. That's a relatively trivial example (just define that as a SHOULD instead of a MUST), but more complex limitations or enhancements may not be so easy to represent.

GitHub Copilot is actually a notable example, as its inputs field changes what the env field means - that's a significant semantic difference that isn't captured well in a schema. If I wanted to move from Copilot to something else, I wouldn't be able to just copy the config object over, since env may not contain raw environment variables, only references to them.

I think there's value in community-adopted conventions or documented implementation recommendations so that equivalent MCP support in different client applications can be used in the same way between them, but making application config spec-defined might be too restrictive.

[jlandowner]

Thanks, @LucaButBoring

Yes, that's why I'm proposing a JSON Schema rather than a configuration file specification.

With a JSON Schema, you are not limited to a specific format—whether the actual settings are in JSON, YAML, or another format—and it can be used within any part of an application-specific configuration.

In addition, by setting additionalProperties to true (default), you allow for custom, application-specific properties while still validating the base configuration against the same specification.

The intention here is to standardize the basic configuration schema and establish a foundation that can accommodate additional specification.
(Also it can simplify the implementation of new MCP Hosts.)

[timheuer]

I was glad to find this issue @jlandowner! I've been using the following as I didn't see even one hosted on schemastore.org or anywhere...

I have been using a local one and just put it on a gist for adding to this discussion:

https://gist.github.com/timheuer/7b092645f01fe15fad2a96677d0b34e6

[rwjblue-glean]

I was glad to find this issue @jlandowner!

Same!

've been using the following as I didn't see even one hosted on schemastore.org or anywhere...

https://gist.github.com/timheuer/7b092645f01fe15fad2a96677d0b34e6

Thanks for sharing @timheuer, this is super useful!

[brainoir]

If you're encountering an ENOENT error when trying to run an MCP server using npm within your Cline configuration, try changing the command from npm to node.

Here's an example of how your configuration might look:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "node",
      "args": [
        "c:\\Users\\onlyo\\Documents\\Cline\\MCP\\filesystem\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js",
        "c:\\Users"
      ],
      "autoApprove": [],
      "disabled": false
    }
  }
}

Key Insights:

• The command should be node.
• The args array should contain:
  • The first argument is always the full path to the installed NPM package's main script (e.g., ...\\<name of your mcp>\\@modelcontextprotocol\\server-<name of your mcp>\\dist\\index.js).
  • Subsequent arguments are optional and specific to the particular MCP server you are running.

[evalstate]

Thank you @timheuer -- this is great. This is something that I think would be good published as part of the CWG site as well as the schema store.

I don't know if there is a shareable update for specifying http servers, or the rules around url only configuration?

[AArnott]

This is the JSON schema that Visual Studio 17.14 uses:
https://gist.github.com/AArnott/ea481eeb07fb78b4b6bf4b7436d88009

[timheuer]

I don't know if there is a shareable update for specifying http servers, or the rules around url only configuration?

@evalstate I just updated my gist to include http -- I think they are intended to be backward compatible actually so one schemaDef actually could be fine (like @AArnott has above) but just separated in this 'just in case' ;-)

[evalstate]

That's great, thanks @AArnott and @timheuer -- I think since SSE is being deprecated, the merged one from @AArnott is probably easier to work with....