Torben Sorensen
83460abce4
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 1m57s
379 lines
11 KiB
Markdown
379 lines
11 KiB
Markdown
# Claude Code MCP Configuration Guide
|
|
|
|
This document explains how to configure MCP (Model Context Protocol) servers for Claude Code, covering both the CLI and VS Code extension.
|
|
|
|
## The Two Config Files
|
|
|
|
Claude Code uses **two separate configuration files** for MCP servers. They must be kept in sync manually.
|
|
|
|
| File | Used By | Notes |
|
|
| ------------------------- | ----------------------------- | ------------------------------------------- |
|
|
| `~/.claude.json` | Claude CLI (`claude` command) | Requires `"type": "stdio"` in each server |
|
|
| `~/.claude/settings.json` | VS Code Extension | Simpler format, supports `"disabled": true` |
|
|
|
|
**Important:** Changes to one file do NOT automatically sync to the other!
|
|
|
|
## File Locations (Windows)
|
|
|
|
```text
|
|
C:\Users\<username>\.claude.json # CLI config
|
|
C:\Users\<username>\.claude\settings.json # VS Code extension config
|
|
```
|
|
|
|
## Config Format Differences
|
|
|
|
### VS Code Extension Format (`~/.claude/settings.json`)
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"server-name": {
|
|
"command": "path/to/executable",
|
|
"args": ["arg1", "arg2"],
|
|
"env": {
|
|
"ENV_VAR": "value"
|
|
},
|
|
"disabled": true // Optional - disable without removing
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### CLI Format (`~/.claude.json`)
|
|
|
|
The CLI config is a larger file with many settings. The `mcpServers` section is nested within it:
|
|
|
|
```json
|
|
{
|
|
"numStartups": 14,
|
|
"installMethod": "global",
|
|
// ... other settings ...
|
|
"mcpServers": {
|
|
"server-name": {
|
|
"type": "stdio", // REQUIRED for CLI
|
|
"command": "path/to/executable",
|
|
"args": ["arg1", "arg2"],
|
|
"env": {
|
|
"ENV_VAR": "value"
|
|
}
|
|
}
|
|
}
|
|
// ... more settings ...
|
|
}
|
|
```
|
|
|
|
**Key difference:** CLI format requires `"type": "stdio"` in each server definition.
|
|
|
|
## Common MCP Server Examples
|
|
|
|
### Memory (Knowledge Graph)
|
|
|
|
```json
|
|
// VS Code format
|
|
"memory": {
|
|
"command": "D:\\nodejs\\npx.cmd",
|
|
"args": ["-y", "@modelcontextprotocol/server-memory"]
|
|
}
|
|
|
|
// CLI format
|
|
"memory": {
|
|
"type": "stdio",
|
|
"command": "D:\\nodejs\\npx.cmd",
|
|
"args": ["-y", "@modelcontextprotocol/server-memory"],
|
|
"env": {}
|
|
}
|
|
```
|
|
|
|
### Filesystem
|
|
|
|
```json
|
|
// VS Code format
|
|
"filesystem": {
|
|
"command": "d:\\nodejs\\node.exe",
|
|
"args": [
|
|
"c:\\Users\\<user>\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js",
|
|
"d:\\path\\to\\project"
|
|
]
|
|
}
|
|
|
|
// CLI format
|
|
"filesystem": {
|
|
"type": "stdio",
|
|
"command": "d:\\nodejs\\node.exe",
|
|
"args": [
|
|
"c:\\Users\\<user>\\AppData\\Roaming\\npm\\node_modules\\@modelcontextprotocol\\server-filesystem\\dist\\index.js",
|
|
"d:\\path\\to\\project"
|
|
],
|
|
"env": {}
|
|
}
|
|
```
|
|
|
|
### Podman/Docker
|
|
|
|
```json
|
|
// VS Code format
|
|
"podman": {
|
|
"command": "D:\\nodejs\\npx.cmd",
|
|
"args": ["-y", "podman-mcp-server@latest"],
|
|
"env": {
|
|
"DOCKER_HOST": "npipe:////./pipe/podman-machine-default"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Gitea
|
|
|
|
```json
|
|
// VS Code format
|
|
"gitea-myserver": {
|
|
"command": "d:\\gitea-mcp\\gitea-mcp.exe",
|
|
"args": ["run", "-t", "stdio"],
|
|
"env": {
|
|
"GITEA_HOST": "https://gitea.example.com",
|
|
"GITEA_ACCESS_TOKEN": "your-token-here"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Redis
|
|
|
|
```json
|
|
// VS Code format
|
|
"redis": {
|
|
"command": "D:\\nodejs\\npx.cmd",
|
|
"args": ["-y", "@modelcontextprotocol/server-redis", "redis://localhost:6379"]
|
|
}
|
|
```
|
|
|
|
### Bugsink (Error Tracking)
|
|
|
|
**Important:** Bugsink has a different API than Sentry. Use `bugsink-mcp`, NOT `sentry-selfhosted-mcp`.
|
|
|
|
**Note:** The `bugsink-mcp` npm package is NOT published. You must clone and build from source:
|
|
|
|
```bash
|
|
# Clone and build bugsink-mcp
|
|
git clone https://github.com/j-shelfwood/bugsink-mcp.git d:\gitea\bugsink-mcp
|
|
cd d:\gitea\bugsink-mcp
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
```json
|
|
// VS Code format (using locally built version)
|
|
"bugsink": {
|
|
"command": "d:\\nodejs\\node.exe",
|
|
"args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
|
|
"env": {
|
|
"BUGSINK_URL": "https://bugsink.example.com",
|
|
"BUGSINK_TOKEN": "your-api-token"
|
|
}
|
|
}
|
|
|
|
// CLI format
|
|
"bugsink": {
|
|
"type": "stdio",
|
|
"command": "d:\\nodejs\\node.exe",
|
|
"args": ["d:\\gitea\\bugsink-mcp\\dist\\index.js"],
|
|
"env": {
|
|
"BUGSINK_URL": "https://bugsink.example.com",
|
|
"BUGSINK_TOKEN": "your-api-token"
|
|
}
|
|
}
|
|
```
|
|
|
|
- GitHub: <https://github.com/j-shelfwood/bugsink-mcp>
|
|
- Get token from Bugsink UI: Settings > API Tokens
|
|
- **Do NOT use npx** - the package is not on npm
|
|
|
|
### Sentry (Cloud or Self-hosted)
|
|
|
|
For actual Sentry instances (not Bugsink), use:
|
|
|
|
```json
|
|
"sentry": {
|
|
"command": "D:\\nodejs\\npx.cmd",
|
|
"args": ["-y", "@sentry/mcp-server"],
|
|
"env": {
|
|
"SENTRY_AUTH_TOKEN": "your-sentry-token"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Server Not Loading
|
|
|
|
1. **Check both config files** - Make sure the server is defined in both `~/.claude.json` AND `~/.claude/settings.json`
|
|
|
|
2. **Verify server order** - Servers load sequentially. Broken/slow servers can block others. Put important servers first.
|
|
|
|
3. **Check for timeout** - Each server has 30 seconds to connect. Slow npx downloads can cause timeouts.
|
|
|
|
4. **Fully restart VS Code** - Window reload is not enough. Close all VS Code windows and reopen.
|
|
|
|
### Verifying Configuration
|
|
|
|
**For CLI:**
|
|
|
|
```bash
|
|
claude mcp list
|
|
```
|
|
|
|
**For VS Code:**
|
|
|
|
1. Open VS Code
|
|
2. View → Output
|
|
3. Select "Claude" from the dropdown
|
|
4. Look for MCP server connection logs
|
|
|
|
### Common Errors
|
|
|
|
| Error | Cause | Solution |
|
|
| ------------------------------------ | ----------------------------- | --------------------------------------------------------------------------- |
|
|
| `Connection timed out after 30000ms` | Server took too long to start | Move server earlier in config, or use pre-installed packages instead of npx |
|
|
| `npm error 404 Not Found` | Package doesn't exist | Check package name spelling |
|
|
| `The system cannot find the path` | Wrong executable path | Verify the command path exists |
|
|
| `Connection closed` | Server crashed on startup | Check server logs, verify environment variables |
|
|
|
|
### Disabling Problem Servers
|
|
|
|
In `~/.claude/settings.json`, add `"disabled": true`:
|
|
|
|
```json
|
|
"problem-server": {
|
|
"command": "...",
|
|
"args": ["..."],
|
|
"disabled": true
|
|
}
|
|
```
|
|
|
|
**Note:** The CLI config (`~/.claude.json`) does not support the `disabled` flag. You must remove the server entirely from that file.
|
|
|
|
## Adding a New MCP Server
|
|
|
|
1. **Install/clone the MCP server** (if not using npx)
|
|
|
|
2. **Add to VS Code config** (`~/.claude/settings.json`):
|
|
|
|
```json
|
|
"new-server": {
|
|
"command": "path/to/command",
|
|
"args": ["arg1", "arg2"],
|
|
"env": { "VAR": "value" }
|
|
}
|
|
```
|
|
|
|
3. **Add to CLI config** (`~/.claude.json`) - find the `mcpServers` section:
|
|
|
|
```json
|
|
"new-server": {
|
|
"type": "stdio",
|
|
"command": "path/to/command",
|
|
"args": ["arg1", "arg2"],
|
|
"env": { "VAR": "value" }
|
|
}
|
|
```
|
|
|
|
4. **Fully restart VS Code**
|
|
|
|
5. **Verify with `claude mcp list`**
|
|
|
|
## Quick Reference: Available MCP Servers
|
|
|
|
| Server | Package/Repo | Purpose |
|
|
| ------------------- | -------------------------------------------------- | --------------------------- |
|
|
| memory | `@modelcontextprotocol/server-memory` | Knowledge graph persistence |
|
|
| filesystem | `@modelcontextprotocol/server-filesystem` | File system access |
|
|
| redis | `@modelcontextprotocol/server-redis` | Redis cache inspection |
|
|
| postgres | `@modelcontextprotocol/server-postgres` | PostgreSQL queries |
|
|
| sequential-thinking | `@modelcontextprotocol/server-sequential-thinking` | Step-by-step reasoning |
|
|
| podman | `podman-mcp-server` | Container management |
|
|
| gitea | `gitea-mcp` (binary) | Gitea API access |
|
|
| bugsink | `j-shelfwood/bugsink-mcp` (build from source) | Error tracking for Bugsink |
|
|
| sentry | `@sentry/mcp-server` | Error tracking for Sentry |
|
|
| playwright | `@anthropics/mcp-server-playwright` | Browser automation |
|
|
|
|
## Best Practices
|
|
|
|
1. **Keep configs in sync** - When you change one file, update the other
|
|
|
|
2. **Order servers by importance** - Put essential servers (memory, filesystem) first
|
|
|
|
3. **Disable instead of delete** - Use `"disabled": true` in settings.json to troubleshoot
|
|
|
|
4. **Use node.exe directly** - For faster startup, install packages globally and use `node.exe` instead of `npx`
|
|
|
|
5. **Store sensitive data in memory** - Use the memory MCP to store API tokens and config for future sessions
|
|
|
|
---
|
|
|
|
## Future: MCP Launchpad
|
|
|
|
**Project:** <https://github.com/kenneth-liao/mcp-launchpad>
|
|
|
|
MCP Launchpad is a CLI tool that wraps multiple MCP servers into a single interface. Worth revisiting when:
|
|
|
|
- [ ] Windows support is stable (currently experimental)
|
|
- [ ] Available as an MCP server itself (currently Bash-based)
|
|
|
|
**Why it's interesting:**
|
|
|
|
| Benefit | Description |
|
|
| ---------------------- | -------------------------------------------------------------- |
|
|
| Single config file | No more syncing `~/.claude.json` and `~/.claude/settings.json` |
|
|
| Project-level configs | Drop `mcp.json` in any project for instant MCP setup |
|
|
| Context window savings | One MCP server in context instead of 10+, reducing token usage |
|
|
| Persistent daemon | Keeps server connections alive for faster repeated calls |
|
|
| Tool search | Find tools across all servers with `mcpl search` |
|
|
|
|
**Current limitations:**
|
|
|
|
- Experimental Windows support
|
|
- Requires Python 3.13+ and uv
|
|
- Claude calls tools via Bash instead of native MCP integration
|
|
- Different mental model (runtime discovery vs startup loading)
|
|
|
|
---
|
|
|
|
## Future: Graphiti (Advanced Knowledge Graph)
|
|
|
|
**Project:** <https://github.com/getzep/graphiti>
|
|
|
|
Graphiti provides temporal-aware knowledge graphs - it tracks not just facts, but _when_ they became true/outdated. Much more powerful than simple memory MCP, but requires significant infrastructure.
|
|
|
|
**Ideal setup:** Run on a Linux server, connect via HTTP from Windows:
|
|
|
|
```json
|
|
// Windows client config (settings.json)
|
|
"graphiti": {
|
|
"type": "sse",
|
|
"url": "http://linux-server:8000/mcp/"
|
|
}
|
|
```
|
|
|
|
**Linux server setup:**
|
|
|
|
```bash
|
|
git clone https://github.com/getzep/graphiti.git
|
|
cd graphiti/mcp_server
|
|
docker compose up -d # Starts FalkorDB + MCP server on port 8000
|
|
```
|
|
|
|
**Requirements:**
|
|
|
|
- Docker on Linux server
|
|
- OpenAI API key (for embeddings)
|
|
- Port 8000 open on LAN
|
|
|
|
**Benefits of remote deployment:**
|
|
|
|
- Heavy lifting (Neo4j/FalkorDB + embeddings) offloaded to Linux
|
|
- Always-on server, Windows connects/disconnects freely
|
|
- Multiple machines can share the same knowledge graph
|
|
- Avoids Windows Docker/WSL2 complexity
|
|
|
|
---
|
|
|
|
\_Last updated: January 2026
|