MCP Config Builder and Checker

Where the config file lives

• Claude DesktopmacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows: %APPDATA%\Claude\claude_desktop_config.json
  Linux: ~/.config/Claude/claude_desktop_config.json
  The easy way: Settings, Developer, Edit Config opens the right file. Remote servers are added under Settings, Connectors, not in this file. Source
• Claude CodeUse claude mcp add. User and local scope are stored in ~/.claude.json; project scope in .mcp.json in the project folder. Source
• CursorAll projects: ~/.cursor/mcp.json in your home folder. One project: .cursor/mcp.json. Source
• VS CodeWorkspace: .vscode/mcp.json, or mcp.json in your user profile. Top-level key servers, and each server has a type. The MCP: Add Server command can write it for you. Source

Windsurf is not covered here yet: its MCP docs now point to a different product, so we could not confirm the current file.

Working examples

One server (Claude Desktop, Cursor, or a Claude Code .mcp.json):

{
  "mcpServers": {
    "flowstate": {
      "command": "/path/to/FlowState/.venv/bin/python",
      "args": ["-m", "flowstate"],
      "env": {
        "FLOWSTATE_DB": "/path/to/flowstate.db",
        "PYTHONPATH": "/path/to/FlowState/mcp-server"
      }
    }
  }
}

Several servers: each one is another named entry inside the same object, separated by a comma.

{
  "mcpServers": {
    "flowstate": {
      "command": "/path/to/FlowState/.venv/bin/python",
      "args": ["-m", "flowstate"],
      "env": {
        "FLOWSTATE_DB": "/path/to/flowstate.db",
        "PYTHONPATH": "/path/to/FlowState/mcp-server"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/Desktop"]
    }
  }
}

A server that needs an API key: the key goes in env. Use a placeholder when you share or paste a config.

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "EXAMPLE_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

The same on Windows: double every backslash.

{
  "mcpServers": {
    "flowstate": {
      "command": "C:\\path\\to\\FlowState\\.venv\\Scripts\\python.exe",
      "args": ["-m", "flowstate"],
      "env": {
        "FLOWSTATE_DB": "C:\\path\\to\\flowstate.db",
        "PYTHONPATH": "C:\\path\\to\\FlowState\\mcp-server"
      }
    }
  }
}

VS Code (.vscode/mcp.json): servers, and a type on every server.

{
  "servers": {
    "flowstate": {
      "type": "stdio",
      "command": "/path/to/FlowState/.venv/bin/python",
      "args": ["-m", "flowstate"],
      "env": {
        "FLOWSTATE_DB": "/path/to/flowstate.db",
        "PYTHONPATH": "/path/to/FlowState/mcp-server"
      }
    },
    "remote-example": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Claude Code, from a terminal:

claude mcp add --transport stdio --scope user flowstate -e FLOWSTATE_DB=/path/to/flowstate.db -e PYTHONPATH=/path/to/FlowState/mcp-server -- /path/to/FlowState/.venv/bin/python -m flowstate
claude mcp add --transport http --scope user remote-example https://example.com/mcp
claude mcp list

I edited it and nothing happened

• Restart fullyQuit the app completely and open it again. Closing the window is not enough for Claude Desktop.
• Right fileCheck the path above for your app and computer. Editing a copy in Downloads or a file with a .txt ending does nothing.
• Valid JSONOne missing comma or an extra one stops every server in the file. Paste it into the checker above.
• Right keymcpServers for Claude Desktop, Claude Code and Cursor; servers for VS Code.
• Full pathsUse full paths in command and in file arguments, not ~ or relative paths.
• Runs by handRun the command and its args in a terminal. If it fails there, it fails in the app too.
• LogsClaude Desktop writes MCP logs to ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows. Cursor shows them in the Output panel under MCP Logs. In Claude Code, run claude mcp list or /mcp.

Local and remote servers

A local server is a program the app starts on your computer from the command in the config. FlowState runs this way, free, and your data stays in one file on your computer.

A remote server is a URL. ChatGPT and Claude in the browser can only use remote servers, because they can't start programs on your computer. To reach your own FlowState from them, FlowState Relay (open in beta) gives your computer a private address without setting up a tunnel, and your data stays on your computer. If you'd rather not run it at home, Hosted keeps it on our server. Both are optional; local FlowState is free.

Questions

• What is claude_desktop_config.json?It is the file where Claude Desktop lists the local MCP servers it starts. Each server has a name, a command, and optional args and env. Claude Desktop opens it for you from Settings, Developer, Edit Config.
• Why does VS Code use "servers" and not "mcpServers"?VS Code has its own format for .vscode/mcp.json, with a top-level "servers" object and a "type" on each server. Claude Desktop, Claude Code and Cursor use "mcpServers". Copying a block between them without renaming the key is a common reason a server never shows up.
• Does this page send my config anywhere?No. The builder and the checker run in your browser. Nothing you type or paste is uploaded or saved. Still, replace real API keys with placeholders before you paste a config anywhere.
• Can ChatGPT or claude.ai use a server from this file?No. These files start servers on your own computer, and only apps on that computer can use them. ChatGPT and claude.ai in the browser connect to remote servers by URL.
• How do I write Windows paths in JSON?Double every backslash, like "C:\\Users\\you\\FlowState". A single backslash breaks the JSON, and the checker points to the exact spot.