Supported input formats

MCPBolt auto-detects the format of whatever you paste. You never need to tell it the format — it reads the shape of the content and picks the right parser. All formats are normalized to the same internal representation before being written out.

Format overview

Claude Desktop / Cursor / Windsurf JSON

The most common format. The top-level key is mcpServers — a map of server name to config object. Used by Claude Desktop, Claude Code, Cursor, Windsurf, Gemini CLI, and Roo.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

For a remote HTTP server, use url instead of command:

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

MCPBolt reads this format as-is and writes the correct native config for every selected target, translating field names where needed (e.g. wrapping in type: "stdio" for VS Code).

VS Code JSON

VS Code uses a servers key (not mcpServers) and requires an explicit type field on every entry.

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

MCPBolt detects the servers + type shape and parses it correctly. When writing to VS Code targets, it adds type automatically; when writing to other targets, it strips it.

Zed context_servers

Zed stores MCP servers inside its settings.json under context_servers. The server command is nested differently:

{
  "context_servers": {
    "filesystem": {
      "command": {
        "path": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      }
    }
  }
}

MCPBolt recognizes the context_servers key and uses the Zed merger (mergeJsonNested) to insert the server without touching any other settings in the file.

Codex TOML

Codex CLI uses TOML for its config. MCP server entries live under [mcp_servers.<name>]:

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem"]

MCPBolt parses pasted TOML and writes the entry with mergeToml, preserving all existing sections.

Continue YAML

Continue stores servers as a YAML array under mcpServers:

mcpServers:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem"]

MCPBolt appends to the array (or updates the entry if a server with the same name already exists) using mergeYamlArray.

npx one-liner

Many server READMEs show a quick npx command. Paste it directly — MCPBolt splits it into command, args, and an inferred server name:

npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

MCPBolt derives the server name from the package name (e.g. server-filesystem) and prompts you to confirm before writing.

Docker command

If a server ships as a Docker image, paste the docker run command:

docker run -i --rm mcp/brave-search

MCPBolt parses this into a stdio server entry using docker as the command and the remaining tokens as args.

Bare URL

If you have just a URL pointing to a remote MCP server, paste it as-is:

https://mcp.example.com/sse

MCPBolt creates a remote server entry with the URL as the transport. It will prompt you for a server name and optional auth headers.