Why MCP client configuration schemas differ

Choose the next guide by what failed

Return to the MCP image-generation learning center when you still need the broader relationship among transport, tools, authorization, generation state, and outputs. Use the error-design guide when the client parsed and connected but the tool returned an authorization, scope, credit, rate, upload, or provider error. Use the stateless-protocol migration page when config parsing succeeds but client and server disagree on the current protocol era. These links address different layers rather than offering another copy of the same configuration.

Read a client configuration as a host adapter, not as MCP wire syntax

MCP standardizes the messages and transport bindings used after a client and server connect. The current protocol defines stdio as newline-delimited JSON-RPC over a client-launched subprocess and Streamable HTTP as POST requests to one MCP endpoint. It also permits custom transports that preserve the protocol's message model. It does not require every host to store connection definitions in one universal JSON key, filename, or serialization format. That host-owned layer explains why two valid clients can describe the same endpoint with different configuration shapes.

The surveyed client references show that a host configuration can contain more than the address of a server. Cursor documents interpolation and OAuth settings; VS Code documents input variables and sandbox rules; Cline examples include enablement and approval fields; Hermes documents per-server tool filters and Claude-code import mapping into YAML; JetBrains AI Assistant documents project-versus-global server level; and Codex documents per-tool approval settings. These are properties of the named clients' configuration surfaces, not fields that every MCP server receives or every host accepts. Copy the connection intent, then rebuild any host controls from the destination client's own reference.

Protocol layer

JSON-RPC messages over a supported transportServer and client must agree on protocol behavior after the connection exists.

Host layer

File location, top-level key, field names, and policyThe client decides how users declare, scope, authorize, and reload a connection.

Portable intent

Local command or remote endpointTranslate that intent into the destination client's documented schema instead of pasting another client's block unchanged.

Use this documentation-verified compatibility matrix

The matrix records the current first-party configuration contract for seven clients as accessed on August 9, 2026. “Documentation-verified” means the named vendor or project currently publishes the file, container key, and connection fields shown here. It does not mean this research installed every client, completed OAuth, or ran a live interoperability suite. Build-specific acceptance remains a separate check.

Cursor uses JSON under `mcpServers` in `.cursor/mcp.json` or `~/.cursor/mcp.json`; a local entry uses `command` and optional `args`, while a remote entry uses `url`. VS Code also uses a file named `mcp.json`, but its top-level object is `servers`; its reference requires a `type` such as `http` or `sse` for remote connections and documents `type: stdio` for local definitions even though a minimal local example omits it. Similar filenames therefore do not imply interchangeable content.

Windsurf and Cline both use `mcpServers`, yet their remote details differ. Windsurf documents `serverUrl` or `url` for remote HTTP. Cline uses `url` and says `type: streamableHttp` should be explicit because omission falls back to legacy SSE. JetBrains AI Assistant also accepts a JSON `mcpServers` snippet with `command`/`args` or `url`, but entry happens through the IDE settings dialog with a project-or-global server level rather than a single shared home-path convention like Cursor. Hermes uses YAML under `mcp_servers`, and Codex uses TOML tables named `[mcp_servers.<name>]`. All seven can express the same basic choice between a command-launched stdio server and a URL-addressed remote server, but the surrounding grammar belongs to the host.

Cursor

JSON: `mcpServers`; local `command`/`args`; remote `url`Documented at project `.cursor/mcp.json` and global `~/.cursor/mcp.json` scopes.

VS Code

JSON: `servers`; remote `type: http|sse` plus `url`Workspace configuration is `.vscode/mcp.json`; a user-profile configuration is also supported.

Windsurf

JSON: `mcpServers`; remote `serverUrl` or `url`The documented raw file is `~/.codeium/mcp_config.json`, and the UI requires a refresh after adding a server.

Cline

JSON: `mcpServers`; remote `type: streamableHttp` plus `url`Omitting remote `type` defaults to legacy SSE according to the current Cline documentation.

JetBrains AI Assistant

JSON: `mcpServers`; local `command`/`args`; remote `url`Configured through Settings with a JSON snippet and a project-or-global server level; not the same file path contract as Cursor.

Hermes Agent

YAML: `mcp_servers`; local `command`/`args`; remote `url`Hermes reads the mapping from `~/.hermes/config.yaml` and documents Claude Code `mcpServers` import into that YAML shape.

Codex

TOML: `[mcp_servers.<name>]`; `command` or `url`Codex reads user configuration from `~/.codex/config.toml` and trusted project configuration from `.codex/config.toml`.

Translate one connection without smuggling in another host's assumptions

Start by classifying the source entry against the two shapes documented by the destination client: a local stdio entry centered on `command` and `args`, or a remote entry centered on `url` or the client's documented URL alias. The seven references do not expose one interchangeable wrapper: they use `mcpServers`, `servers`, YAML `mcp_servers`, or TOML server tables. Preserve the server name as a human label, but rebuild the destination entry from that client's reference rather than renaming only the outer key.

For a remote endpoint, verify whether the destination infers HTTP from `url` or requires an explicit type. Cursor's primary remote example uses `url` without a type. VS Code requires `type` for HTTP or SSE in its reference. Cline's current documentation gives the sharper warning: leaving out `type` chooses legacy SSE, so a Streamable HTTP endpoint should say `streamableHttp`. Windsurf accepts either `serverUrl` or `url`. JetBrains remote examples use `url` inside an `mcpServers` object. These are client parser behaviors, not alternative names sent over MCP.

For a local server, treat argument conversion as a checklist rather than a promise of mechanical portability: transcribe each documented argument in order, adapt quoting to JSON, YAML, or TOML, and verify paths on the machine that will launch the process. Do not assume a placeholder syntax carries across hosts. Hermes documents that Claude Code `mcpServers` maps into Hermes YAML `mcp_servers` through an import path, which is an explicit translation aid rather than proof that every field is interchangeable. Where a destination documents an input, environment, OAuth, header, or approval mechanism, use that mechanism and inspect the saved entry before starting a third-party server.

Step 1

Classify local stdio versus remote HTTPDo not carry both `command` and `url` merely because they appeared in different examples.

Step 2

Recreate the destination container and transport fieldsUse `servers`, `mcpServers`, `mcp_servers`, or a TOML table only where that client documents it.

Step 3

Rework secrets, scope, and reload behaviorIf parsing succeeds but connection fails, investigate the destination client's credential, scope, trust, and reload guidance.

Keep this matrix narrow, dated, and unpublished

This page owns the concept “mcp client config schemas”: why host configuration differs and how to translate the same connection intent across current clients. It does not claim that matching JSON keys establish protocol compatibility, that every client supports every MCP capability, or that a documentation example passed a live connection test. The matrix is documentation-verified as of August 9, 2026 and needs monthly rechecking because client parsers, paths, transport defaults, and authentication flows can change independently.

As a research-method decision, the recent-evidence output was reviewed but not used to substantiate reader-facing claims: coverage was degraded by a missing optional X lane and a partial Reddit lane, and only one retrieved item cleared the relevance floor for host configuration schemas. This is recorded as degraded coverage and insufficient community evidence, not as proof that unavailable communities were silent. The page therefore makes no claim about community consensus, adoption, or practitioner outcomes.

No client was installed or driven through a live server connection for this research, so the required compatibility matrix remains a first-party-documentation matrix rather than a build-by-build acceptance ledger. Before publication, an editor should decide whether that evidence level satisfies the page promise or whether to add dated tests for the specific clients and transports readers will rely on. Until then, keep status draft, preserve the evidence gap, and avoid converting a published schema into an unqualified working-compatibility promise.