MCP servers for coding agents: a practical setup guide

The mental model

Model Context Protocol (MCP) is a standard way to plug tools into an agent. Three terms and you're fluent:

• An MCP server is a small process that exposes tools — read_file, query, create_issue — to your agent.
• Your agent is the MCP client. You tell it which servers to launch.
• Servers run locally as subprocesses (stdio — the common case) or connect to a remote URL (HTTP/SSE).

The trade-off to keep in your head: more servers = more capability, but more tokens and more risk. Every connected server advertises its tools into the context window before you type a word. Enable only what you'll use this week.

Where the config lives

Both major tools use the same JSON shape — a top-level mcpServers object mapping a name to either { command, args, env } (stdio) or { url } (remote).

• Claude Code — .mcp.json at the repo root (project), or ~/.claude.json (global). CLI helper: claude mcp add ....
• Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), plus a Settings → MCP toggle UI.

Fastest path on Claude Code: claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD", then claude mcp list to confirm it registered. On Cursor, drop the same mcpServers block into .cursor/mcp.json and check for a green/connected status in the panel.

The starter set (what to actually install)

Start with two. Add the rest only when a real task demands it.

1. filesystem — scoped file read/write. The single most useful server. Scope it to your project path, never your home directory.
2. git — history, diff, blame, log. Lets the agent reason about change, not just current state.
3. fetch — pull a URL into context so the agent can read the docs or spec it needs.
4. github — issues, PRs and code search via the official GitHub MCP server. Use a fine-grained, repo-scoped, least-privilege token.
5. postgres / sqlite — let the agent inspect schema and run queries. Use a read-only role on a non-prod database.
6. playwright — drive a real browser for end-to-end debugging. Heavier; enable on demand.

A sane .mcp.json to start with

This is the whole thing for day one. Verify each server connects before adding the next.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/abs/path/to/project"]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/abs/path/to/project"]
    }
  }
}

Use absolute paths — ~ and relative paths often don't expand the way you expect inside a subprocess. Add fetch, then github, then a database server as tasks demand them.

Security — read this before adding tokens

MCP servers run with your privileges and can touch real systems. Treat adding one like giving the agent your shell.

• Least privilege, always. Read-only DB users. Fine-grained, repo-scoped, read-only tokens. Filesystem scoped to one project path.
• Never commit secrets. Keep tokens in environment variables or your tool's secret store — commit a .example file, not your real .mcp.json.
• Non-prod by default. Point database and infra servers at staging or local. The agent should never hold prod write credentials.
• Mind SSRF. A fetch server aimed at attacker-controlled URLs can reach internal services. Don't combine broad network tools with untrusted input carelessly.
• Audit the surface. Run claude mcp list (or open Cursor's MCP panel) and remove servers you're not using. Each one is attack surface and token cost.
• Vet the publisher. Prefer official (@modelcontextprotocol/*) or vendor-published servers over random packages. You're running their code.

Gotchas that waste an afternoon

• It won't connect. 90% of the time it's a missing runtime: npx needs Node, uvx needs uv, the GitHub image needs Docker. Install the runtime, then restart the agent.
• Restart required. Most clients only read MCP config at startup. Edit → restart Claude Code / reload Cursor.
• Token bloat. Ten servers can eat thousands of tokens before you type anything. Keep the set lean.
• Package names drift. The ecosystem moved fast and some reference servers were archived or handed to vendors — notably the old npm Postgres and GitHub reference servers are deprecated in favor of the vendor builds. If a @modelcontextprotocol/server-X command 404s, search for the current official package and update it.
• Windows quoting. You may need cmd /c npx ...; macOS and Linux use npx/uvx directly.

That's the whole game: start with filesystem and git, scope everything tightly, add a server only when a task needs it, and restart after every config change. Once your agent can read the repo, reason about diffs, and pull the right docs on its own, the gap between "fancy autocomplete" and "teammate" closes fast — and a tight rules file plus disciplined prompts do the rest.