Proposal: Standardizing MCP Configuration File Format #681

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

Why This Matters

JSON is the current standard for MCP configuration files (often called mcp.json, typically has an mcpServers key), and it’s used across tools like Claude Desktop, Cursor, etc. However, I'm not aware of any specification to ensure consistency across implementations (though luckily it seems to have evolved to be rather consistent). Standardizing the JSON format in the MCP spec would prevent future divergence and make it easier to evolve the format over time.

JSON example

I think people are pretty familiar with this config file, but I'll include an example to make absolutely sure we're on the same page:

{
  "mcpServers": {
    "computer-control-mcp": {
      "command": "uvx",
      "args": ["computer-control-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    },
    "selenium": {
      "command": "npx",
      "args": ["-y", "@angiejones/mcp-selenium"]
    },
    "utc_time": {
      "url": "http://utc-time-mcp-server.company.com/mcp"
    },
    "adobe_firefly": {
      "type": "stdio",
      "env": {
        "FIREFLY_CLIENT_ID": "xyz",
        "FIREFLY_CLIENT_SECRET": "123"
      },
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/msabramo/python-firefly[mcp-server]",
        "mcp-server"
      ]
    },
    "postgres": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Currently, I have very similar files for Claude Desktop and Cursor, but my fear is that as MCP evolves to have new features, different tools may end up specifying things in different ways and then it will be extra cognitive load to maintain these files.

This format is simple, widely supported, and works well for MCP tools. By formalizing this schema, we can ensure all tools interpret configurations consistently.

Why Standardization Matters

Standardizing the JSON format ensures:

• Consistency: All MCP tools will interpret configurations the same way.
• Ease of Use: Users can confidently share and reuse configuration files across tools.
• Future-Proofing: A formal schema makes it easier to introduce new features without breaking existing setups.

Example of future-proofing: Adding a YAML variant of the same configuration file

While JSON is the current standard, some users might prefer YAML for its flexibility and readability. YAML offers:

• Support for Comments: Useful for documentation or temporarily disabling configurations.
• Forgiving Syntax: YAML is less error-prone, especially for manual edits. For example, JSON parsers get upset if you include a comma at the end of the last item in a list. This tends to lead to annoying errors when copying and pasting JSON snippet.
• Compactness: YAML files are often more concise and easier to read. And the compactness leaves more room for comments, already mentioned above, which could be very helpful for explaining things.

For example, the JSON configuration I included above is more readable in YAML:

mcpServers:
  # Server for computer control tasks
  computer-control-mcp:
    command: uvx
    args:
      - computer-control-mcp@latest

  # Playwright MCP server for browser automation
  playwright:
    command: npx
    args:
      - "@playwright/mcp@latest"

  # Selenium MCP server for web testing
  selenium:
    command: npx
    args:
      - -y  # Ensures confirmation prompts are skipped
      - "@angiejones/mcp-selenium"

  # Server providing UTC time services
  utc_time:
    url: http://utc-time-mcp-server.company.com/mcp

  # Adobe Firefly MCP server with environment variables for authentication
  adobe_firefly:
    type: stdio
    env:
      FIREFLY_CLIENT_ID: xyz  # Adobe Firefly client ID
      FIREFLY_CLIENT_SECRET: 123  # Adobe Firefly client secret
    command: uvx
    args:
      - --from
      - git+https://github.com/msabramo/python-firefly[mcp-server]
      - mcp-server

  # Local PostgreSQL MCP server
  postgres:
    url: http://localhost:3000/mcp

Aside from looking cleaner, this MCP configuration is easier to maintain, as the need for commas has been removed so we no longer have to worry about pasting a snippet in and having to add or remove commas. Since YAML is a superset of JSON, a snippet that ends with a comma could be pasted in anywhere and it should work. In fact, people that don't love YAML but like some aspects of it, like comments and its forgiveness for extra commas, could opt to still essentially use JSON syntax, but have it be a better JSON.

To be clear, I am not advocating removing the JSON format - I think it should absolutely be kept for backwards compatibility and I don't want to force YAML on anyone as I know a lot of people dislike it. In fact, since YAML is a superset of JSON, it seems it would be pretty easy for clients to support YAML and continue to support the JSON format with little or no changes. I would advocate that any development of this include testing to ensure that current mcp.json files still work.

Another example of future-proofing: Making it clear that command can have full command and don't have to split out arguments into a list in args

My examples above separate the command and args because this is what I've seen everywhere that I've looked, so I've followed that pattern. One day, I expressed a desire to Cursor devs to simply paste a full shell command into the command key and not mess with args and I was told (but haven't verified yet) that I can do this very thing in Cursor and it works. E.g.:

    "adobe_firefly": {
      "type": "stdio",
      "env": {
        "FIREFLY_CLIENT_ID": "xyz",
        "FIREFLY_CLIENT_SECRET": "123"
      },
      "command": "uvx --from git+https://github.com/msabramo/python-firefly[mcp-server] mcp-server"
    },

I think I haven't tried this out in part because I fear that I might get accustomed to it and then find it doesn't work in other MCP tools. So I'd love to see a specification for the configuration file format that makes it clear that this is allowed, because even if all the tools actually support this, it seems to be not well-known.

Note that if we combine this simple command syntax with YAML, then we get something that looks quite nice:

adobe_firefly:
  type: stdio  # Communication type (standard input/output)
  env:
    FIREFLY_CLIENT_ID: xyz  # Adobe Firefly client ID for authentication
    FIREFLY_CLIENT_SECRET: 123  # Adobe Firefly client secret for authentication
  command: >  # Command to execute (using folded style for readability)
    uvx --from git+https://github.com/msabramo/python-firefly[mcp-server] mcp-server

Just a few ideas. Would love to hear other people's thoughts and discuss.

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other