Content
<p align="center">
<img src="assets/hero.png" alt="mcp-config-cookbook — copy-paste MCP server configs for Claude Code, Cursor, Windsurf and VS Code, with a generator that emits the exact JSON per client" width="840">
</p>
# mcp-config-cookbook — MCP server configs for Claude Code, Cursor, Windsurf & VS Code
> The same MCP server needs **slightly different JSON in every client** — different top-level key, different file location, different secret handling, and a Windows `npx` gotcha that breaks half the setups. This is the copy-paste reference, plus a tiny generator (`mcpgen`) that emits the **exact** block for the client you're using.
The Model Context Protocol is everywhere now, but the config format is *almost* standard — and the small differences are exactly what cost you 20 minutes of "why won't it connect." This repo collects the working configs in one place.
## The one table that explains the differences
| Client | Top-level key | Config file | `${VAR}` expansion |
|---|---|---|---|
| **Claude Code** | `mcpServers` | `./.mcp.json` (project) · `~/.claude.json` (user) | ✅ `${VAR}` and `${VAR:-default}` |
| **Cursor** | `mcpServers` | `./.cursor/mcp.json` · `~/.cursor/mcp.json` | — |
| **Windsurf** | `mcpServers` | `~/.codeium/windsurf/mcp_config.json` | — |
| **VS Code** | **`servers`** ⚠️ | `./.vscode/mcp.json` | ✅ + `inputs` for prompted secrets |
> ⚠️ **VS Code is the trap:** the key is **`servers`**, not `mcpServers`. Paste a `mcpServers` block into `.vscode/mcp.json` and it silently does nothing.
## Generator — get the exact block
```bash
npx mcp-config-cookbook --help # or: npx mcpgen --help after install
```
```bash
# stdio server (the common case)
npx mcpgen --client claude-code --name github \
--command npx --args "-y @modelcontextprotocol/server-github" \
--env GITHUB_TOKEN=ghp_xxx
# remote (HTTP) server
npx mcpgen --client cursor --name linear --url https://mcp.linear.app/sse
# Windows: wrap npx in `cmd /c` (see gotchas below)
npx mcpgen --client claude-code --name fs \
--command npx --args "-y @modelcontextprotocol/server-filesystem ." --windows
```
It prints the right key (`mcpServers` vs `servers`), the right shape (stdio vs `{type:"http",url}`), and tells you which file to paste into.
## Copy-paste: a `github` server in every client
**Claude Code** — `./.mcp.json`
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
}
}
```
**Cursor** — `./.cursor/mcp.json` · **Windsurf** — `~/.codeium/windsurf/mcp_config.json` (identical shape)
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "ghp_xxx" }
}
}
}
```
**VS Code** — `./.vscode/mcp.json` (note `servers` + `inputs`)
```json
{
"inputs": [
{ "id": "github_token", "type": "promptString", "description": "GitHub token", "password": true }
],
"servers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${input:github_token}" }
}
}
}
```
**Remote (HTTP/SSE) server** — Claude Code / Cursor / Windsurf
```json
{
"mcpServers": {
"linear": { "type": "http", "url": "https://mcp.linear.app/sse" }
}
}
```
## Windows gotchas (the part nobody documents)
- **`npx`/`npm` need a `cmd /c` wrapper.** On Windows, spawning `npx` directly often fails with `ENOENT`. Use `"command": "cmd"`, `"args": ["/c", "npx", "-y", "<server>"]`. The generator does this with `--windows`.
- **Paths use backslashes and need escaping in JSON** (`C:\\Users\\you\\project`) — or just use forward slashes, which work.
- **Config file locations** resolve `~` to `%USERPROFILE%` (e.g. `C:\Users\you\.cursor\mcp.json`, `C:\Users\you\.codeium\windsurf\mcp_config.json`).
## Secrets
- **Don't hardcode tokens** in a project file you commit. Use env expansion (`${GITHUB_TOKEN}` in Claude Code / VS Code), VS Code `inputs`, or your OS keychain.
- Want to make sure you didn't leave a key in a config? Scan it with [`claude-guard`](https://github.com/novalidesignl-ship-it/claude-guard).
## Scope & honesty
- Covers **Claude Code, Cursor, Windsurf, and VS Code** today. PRs welcome for Codex, Zed, JetBrains, and others.
- Client config formats **drift** — when in doubt, check the client's own docs. This repo is dated and versioned so you can tell how current it is.
- `clients.json` is the machine-readable source of truth (import it into your own tooling).
## License
[MIT](./LICENSE) © novalidesignl-ship-it
---
*Independent open-source reference. Not affiliated with Anthropic, Cursor, Codeium/Windsurf, or Microsoft.*
