Setting up MCP servers: give Claude Code real tools

What MCP actually adds

Out of the box, Claude Code reads and writes files in the folder you launched it in. That is enough for most coding work. MCP servers are how you grant it more. They are small processes that expose tools through a shared protocol, so Claude Code can query your database, open issues on GitHub, search your Notion, or hit your internal APIs without you pasting credentials into chat. The protocol is open and the servers are reusable, which means once you wire one up you can take it from project to project.

Think of MCP servers as plug ins for Claude Code that you control. Each server defines a set of tools, the names of those tools, and the arguments they expect. Claude Code lists them at session start, picks which to call based on what you ask, and shows you the call before it runs anything that mutates state. You decide which servers are enabled and which are off. The configuration lives in a single JSON file in your home directory.

Where the config lives

Claude Code reads its MCP configuration from a file in your home directory under the .claude folder. The file is JSON and has one top level key that lists each server by name. Each server entry describes how to launch the server process, what command to run, what arguments to pass, and what environment variables it needs. You can edit this file by hand or with any editor. There is no special tooling required, and members at claudecodeclub.ai keep example configs in a shared repo so you do not have to start from scratch.

Filesystem MCP for scoped file access

The Filesystem MCP server is the simplest server to add and one of the most useful. It exposes file read and write tools against a list of directories you specify. Why add it when Claude Code can already touch files. Because the Filesystem MCP can point at folders outside the current project, like a shared notes directory or a documents folder, and let Claude Code work across them in a controlled way. Configure it with the exact directories you want exposed, and nothing else is visible.

A common setup pattern is to point the Filesystem MCP at three folders. A notes folder where you keep specs and design docs, a snippets folder where you keep reusable code blocks, and a templates folder where you keep boilerplate for new projects. With those three exposed, your sessions get richer because Claude Code can pull in the right context without you copying files around. Keep the list short. Three to five folders is the sweet spot. More than that and the model starts ranging too widely for simple tasks.

• Use it to expose a notes folder so Claude Code can read your spec while editing a different repo
• Point it at a shared assets folder if you reuse images and copy across multiple sites
• Set the allowed directories explicitly, never to your home folder root
• Restart the claude session after editing the config so the new server is picked up
• Confirm the server loaded by asking Claude Code which tools are available in this session

GitHub MCP for repo work

The GitHub MCP server lets Claude Code open issues, create pull requests, read repository metadata, and search across your repos without you switching to a browser. The setup needs a GitHub personal access token with the scopes you actually want exposed. Repo for private repo access, workflow if you want it touching Actions. Generate the token, store it in an environment variable, and reference that variable in the MCP config. Do not paste the token into the JSON directly.

Pay attention to token expiration when you generate it. A token that expires in ninety days is fine and forces a regular rotation, which is good hygiene. A token with no expiration is convenient and a long term risk. Pick the trade you can live with and put a calendar reminder a few days before the expiration date so the rotation does not surprise you mid sprint. The GitHub MCP setup repays this discipline daily, since most of the friction in repo work comes from context switches you no longer have to make.

Once it is wired, you can ask Claude Code to draft a PR description from the diff you just made, open an issue with a template you prefer, or pull the last five issues tagged bug into the session as context. The first time you ask for a PR to be created, Claude Code shows you the title, body, and target branch before it actually calls the API. That confirmation step is your safety net.

Postgres MCP for database aware coding

If you write SQL, the Postgres MCP server is the one that earns its keep fastest. Point it at a connection string, optionally restrict it to read only, and Claude Code can introspect tables, write queries against your real schema, and verify a migration plan before you run it. The read only mode is a strong default for production databases. For local development databases, full access is fine and makes the iteration loop much tighter.

1. 1Create a database user with the exact permissions you want exposed, not your admin user
2. 2Build the connection string and store it in an environment variable in your shell config
3. 3Add the Postgres MCP entry to your Claude Code config with the environment variable reference
4. 4Restart your claude session and ask it to list the tables as a sanity check
5. 5Set read only at the MCP level for any database that touches production data

Other servers worth knowing about

There is a growing ecosystem of MCP servers. Servers for Slack, for Notion, for Linear, for Stripe, for Fly, for Vercel, for browser automation, for vector databases. Most of them follow the same setup pattern. Install the server package, add an entry to the config, set a credential as an environment variable, restart the session. Pick the ones that match the tools you already use. Adding a server you do not actually need only adds noise to tool selection.

Debugging a server that will not start

When an MCP server fails to load, Claude Code shows a short error at session start and continues without it. The error is usually one of three things. The command in the config is wrong or not on the PATH. The environment variable the server expects is missing. Or the credential the server got is invalid. Each of these has a clean fix and none of them require deep debugging once you know what to look for.

Start by running the server command directly in your terminal. If it fails there, it will fail under Claude Code. Read the error. Then check that any environment variable the server expects is actually set in the shell that launches claude, not just in another tab. New shells get a fresh environment. If you set a variable in one terminal and started claude in another, the new terminal does not see it. This single mistake accounts for most reported MCP issues on day one.

Picking the right first servers

If you are setting up MCP for the first time, do not add five servers at once. Add the GitHub MCP if you do real PR work in your job, add the Filesystem MCP if you keep notes outside your repo, add the Postgres MCP if you write SQL. Three is a good ceiling for week one. After a week of real use you will know which one earned its place and which one you never call. Remove the unused ones from the config so tool selection stays sharp.

Per project versus global config

Your global MCP config applies to every Claude Code session. Some servers belong everywhere, like the GitHub MCP if you do PR work across many repos. Others belong to a single project, like a Postgres MCP pointed at a specific database. Use per project overrides when your version supports them. The override file lives in the project root and adds or replaces entries for that project only. The result is a clean global default and project specific extras that travel with the repo and onboard new contributors automatically.

Local versus remote MCP servers

Most MCP servers run locally on your machine. The config tells Claude Code to launch the server as a subprocess, and the two talk over standard input and output. Local servers are private, fast, and easy to debug because you can run them by hand. Some servers run remotely, exposed over HTTP, and you connect to them with a URL and an auth header. Remote servers are useful for shared team tools, but they introduce network failure modes that local servers do not have. Start local. Move to remote only when the shared use case actually justifies it.

When you connect to a remote MCP server, treat the URL like a credential. Do not paste it into chats, do not commit it. If the remote server requires a token, use the same environment variable pattern you use for local servers. The protocol does not care whether the server is across the room or across a continent, but the security surface area is different and you should adjust your habits accordingly.

Tool noise and how to manage it

Every MCP server adds tools to the list Claude Code can pick from at each turn. Five servers can mean fifty tools. That is fine in principle and noisy in practice. The signal that you have too many tools enabled is that Claude Code starts picking the wrong one for simple tasks, or asks you which to use when the right answer is obvious. The fix is to scope. Disable servers you do not need in a given project by commenting them out in the config or by using a per project config override if your version supports one.

Naming matters too. If two servers expose tools with similar names, Claude Code will sometimes coin flip between them. Rename them in your config to disambiguate. The github MCP issue creation tool can be called github_create_issue and the linear MCP one can be called linear_create_issue. Two words of clarity for a year of fewer wrong tool picks is a great trade. The shared config templates at claudecodeclub.ai already follow this convention so you can borrow the naming rather than invent it.

Where this fits in your workflow

MCP is the quiet upgrade that takes Claude Code from a coding assistant to a workspace assistant. Once it can read your real schema and open your real PRs, you stop copying things between tabs. The setup is small, the payoff is daily. For a project to project workflow that pairs MCP with the right git habits, the /guides/git-workflow-with-claude-code guide is the right next step, and the $9 club at claudecodeclub.ai keeps a maintained list of which servers are currently worth using.