MCP Playbook
Model Context Protocol (MCP) MCP (Model Context Protocol) A standard for connecting AI to external tools and data sources. Lets Claude access databases, APIs, and services beyond just text. "Like USB ports for AI. A universal way to plug in new capabilities."
1What is MCP?
MCP (Model Context Protocol) is a standard that lets AI assistants connect to external tools and data sources. Think of it as USB ports for AI — a universal way to plug in new capabilities.
Without MCP vs With MCP
Without MCP
- • Claude can only see what you paste
- • No access to your files
- • Can't search the web
- • Can't query databases
With MCP
- • Claude reads your project files
- • Searches the web for answers
- • Queries your Postgres database
- • Runs commands in your terminal
Filesystem
Read and write local files
Brave Search
Search the web for real-time info
PostgreSQLPostgreSQL
A powerful, open-source relational database. Rock-solid, feature-rich, and the choice for serious production apps.
"Like the Toyota Camry of databases. Reliable, well-documented, handles anything you throw at it."
PostgreSQL
A powerful, open-source relational database. Rock-solid, feature-rich, and the choice for serious production apps.
"Like the Toyota Camry of databases. Reliable, well-documented, handles anything you throw at it."
Query your database directly
2Claude Code vs Claude Desktop
MCP works differently depending on how you're using Claude. Here's the key difference:
Claude Code
CLI in your terminal
- Already has filesystem access built-in
- Can run terminal commands natively
- MCP adds extras: Brave, Postgres, etc.
Config: ~/.claude/settings.json
Claude Desktop
GUI app for macOS/Windows
- No filesystem access by default
- Can't run commands without MCP
- MCP unlocks everything
Config: claude_desktop_config.json
Key Insight: Claude Code is already powerful out of the box. You add MCP servers for extra capabilities like web search or database access. Claude Desktop needs MCP to do anything beyond chat.
3Config File Locations
Each environment stores its MCP config in a different place:
Claude Desktop (macOS)
Claude Desktop (Windows)
Claude Code (Global)
Applies to all projects
Claude Code (Per-Project)
Overrides global settings for this project only
4Popular MCP Servers
Filesystem
Read and write files on your computer
"@anthropic/mcp-server-filesystem"
Note: Claude Code has this built-in. Only needed for Claude Desktop.
Brave Search
Search the web for real-time information
"@anthropic/mcp-server-brave-search"
Requires: A Brave API key (free tier available)
PostgreSQL (Neon)
Query your database directly from Claude
"@anthropic/mcp-server-postgres"
Requires: DATABASE_URL connection string
GitHub
Create PRs, manage issues, search repos
"@anthropic/mcp-server-github"
Requires: GitHub personal access token
5Example Configurations
Claude Desktop Config
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-filesystem", "/Users/you/projects"]
},
"brave-search": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-brave-search"],
"env": { "BRAVE_API_KEY": "your-key-here" }
}
}
}
Claude Code Config (~/.claude/settings.json)
{
"mcpServers": {
"neon": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-postgres", "$DATABASE_URL"]
}
}
}
Claude Code reads DATABASE_URL from your shell environment or .env.local
6Common Pitfalls
"Server not found" after editing config
You edited the config, but Claude still doesn't see the server.
Fix: Restart Claude Desktop completely (quit and reopen). For Claude Code, start a new session. MCP servers are loaded at startup.
JSON syntax errors
Config file isn't loading because of a typo or missing comma.
Fix: Use a JSON validator or our MCP Configurator to generate valid JSON. Common issues: trailing commas, missing quotes.
Environment variables not loading
Your API key or DATABASE_URL isn't being picked up.
Fix: For Claude Desktop, put env vars directly in the config under "env". For Claude Code, ensure they're in your shell profile or .env.local.
Filesystem server can't access files
Claude says it can't read files even though filesystem server is configured.
Fix: The filesystem server only has access to directories you explicitly list in the args. Add the full path to your project folder.
Windows path issues
Paths with backslashes or spaces causing errors on Windows.
Fix: Use forward slashes (C:/Users/you) or escape backslashes (C:\\Users\\you). Avoid spaces in paths if possible.
7Pro Tips
Use project-level configs for sensitive servers
Don't put your production DATABASE_URL in the global config. Use a .claude/settings.json in each project folder. This way, different projects connect to different databases.
Claude Code + Brave Search = Research Mode
Add Brave Search to Claude Code when you need to look up docs, find examples, or check current best practices. It's like giving Claude access to Stack Overflow in real-time.
Test with a read-only database first
When setting up the Postgres MCP server, start with a read-only connection string or a dev branch. Claude can execute queries — make sure you trust what it's doing before giving write access.
Verify servers are loaded
In Claude Code, run /mcp to see which MCP servers are currently active. In Claude Desktop, check the plugin icon in the sidebar. If your server isn't listed, the config isn't loading correctly.
Keep API keys out of version control
If you're committing .claude/settings.json to your repo (for team consistency), use environment variable references like $BRAVE_API_KEY instead of hardcoding keys.
8Things to Remember
MCP servers run locally on your machine, not in the cloud
Each server is an npm package that Claude launches via npx
Servers are loaded at startup — restart to pick up changes
Claude Code has built-in file and terminal access; MCP extends it
Env vars in Claude Desktop go in the config file, not your shell
Project configs override global configs in Claude Code
Use absolute paths in filesystem server args
Brave Search needs a free API key from brave.com
Ready to configure?
Use our tool to generate the perfect MCP config for your setup.