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.

Writing the MCP config by hand

The MCP config format is straightforward JSON. Each server entry has a name you choose, a command key pointing at the executable, an args array for arguments, and an env object for environment variables the server needs. A minimal Filesystem MCP entry tells Claude Code to run the mcp-server-filesystem npm package with a list of allowed directory paths. A GitHub MCP entry tells it to run the GitHub server package with a GITHUB_PERSONAL_ACCESS_TOKEN env var reference. The pattern is the same for every server - command, args, env - and reading one working example makes the rest easy to write.

Be careful with relative paths in the config. Relative paths resolve relative to where the claude command is run, not relative to the config file. Absolute paths are safer and clearer. Use your home directory path explicitly rather than relying on tilde expansion, since some shells do not expand tilde inside a JSON file the way you might expect. When in doubt, paste the absolute path and move on.

Testing a new server before you rely on it

After adding a new server, restart Claude Code and ask it which tools are available in this session. The response names every tool each loaded server exposes. If a server you added is missing from the list, it failed to start. Scroll up past the session prompt to see whether there is a startup error message. Claude Code logs a short error per failed server rather than crashing, so the failure is easy to miss if you do not look for it.

1. 1Add the server entry to the config with the correct command and env var names
2. 2Start a fresh Claude Code session so the new config is loaded
3. 3Ask which tools are available and confirm the new server's tools appear by name
4. 4Run one simple tool call - like listing tables for Postgres or listing files for Filesystem
5. 5If the tool does not appear, check the startup log, then run the server command in terminal to see the raw error

MCP and the claude code CLI distinction

MCP servers are a Claude Code feature - they run in the context of the interactive claude code CLI session. They are not available to the Claude CLI one-shot tool or to the claude.ai web chat interface. If you write a shell script that pipes to the Claude CLI for a batch job, none of your MCP tools are active in that call. The tool that has your GitHub MCP and your Postgres MCP is the claude command you launch interactively. Design your automation accordingly - use the interactive claude code session when you need MCP tools, and use the CLI when you want a simple stateless call.

Server health and the daily startup check

Add a quick health check to your morning workflow. When you first open Claude Code, glance at the startup output for any server that failed. It takes three seconds. A server that fails silently for a week is a week of worse sessions where you did not know a tool was missing. The most common daily failure is an expired token on the GitHub MCP when a short-lived personal access token hits its expiration date mid week. That five second token renewal keeps the rest of the day smooth.

If you use environment variables loaded by a tool like direnv or dotenv, confirm that those variables are set in the shell that launches Claude Code, not just in specific project directories. MCP servers start before Claude Code reads any project context, so a server that needs a database URL from a project .env file will fail unless that variable is in the outer shell environment. Pull project-specific credentials into your shell profile or use a shell wrapper that sources them before launching the session.

Building a custom MCP server

The MCP protocol is open and the tooling to build a server is lightweight. If you have an internal API, a custom data source, or a workflow that does not have a published server yet, you can write one. The server exposes a manifest of tool names and schemas, and responds to tool calls with JSON. A minimal working server takes an afternoon to build in TypeScript or Python. The Anthropic documentation includes starter templates and the Claude Code Club community shares custom server code at claudecodeclub.ai.

Before you build a custom server, check whether an existing one already covers the need. The ecosystem grew quickly and servers exist for most popular SaaS tools, databases, and cloud providers. The cases that genuinely need custom work tend to be internal company APIs, proprietary data formats, and workflow orchestration specific to one organization. If your internal tool has a REST API with decent documentation, Claude Code can often help you scaffold the custom server in one session.

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.