Configure Claude Code MCP Servers

Start smaller than the config file suggests. A Claude Code MCP setup should begin with scope, secrets, permissions, and one repeatable test, not with a pile of integrations copied from an MCP desktop example.

This is how I teach it in a Claude Code workshop: add one server, make its boundary explicit, prove the workflow, then share the convention with the team. The setup work is not hard, but the team agreement matters because MCP connects Claude Code to systems that can read private data or take action outside the repository.

Choose the smallest useful scope

Do not make the first MCP server global unless every repository needs it. For most Claude Code teams, the safer first move is a project-scoped server for one repository or a local setup for one developer while the workflow is still being checked.

A useful rule is simple: if the integration encodes a team convention, put the decision where the team can review it. If it is personal tooling or a one-off credential, keep it local.

For example, in a Next.js repo with apps/web and packages/ui, a browser or design-review MCP server might only be needed when checking UI behavior in apps/web. That does not justify giving every repo the same server by default.

Configure the server in this order

Treat Claude Code MCP server configuration as a small engineering change. The config line matters, but the order of decisions matters more.

1. Name the job the server is allowed to do.
2. Pick the scope: local, project, user, or managed by the organization.
3. Choose the transport and command or URL from the server documentation.
4. Put secrets in environment variables or the approved secret store, not in the repo.
5. Decide whether the server is read-only, write-capable, or human-approved for writes.
6. Add one test prompt that proves the integration works without touching production data.
7. Record the owner who will remove or update the server when it stops being useful.

This is a Review step in our methodology: check the integration boundary before you delegate broader work to it. It also fits naturally with Team conventions, because the same server should not behave differently for each developer unless that difference is intentional.

Write down the permission note

A team does not need a long policy for every MCP server. It does need a short record that says what the server is for, how it is configured, and what Claude Code must not do with it.

Paste this into the pull request, internal runbook, or repository docs before sharing the setup. CLAUDE.md can point to this note if agents need to remember the rule, but do not turn CLAUDE.md into a secret store or a full integration manual.

## MCP server record

| Field | Team decision |
| --- | --- |
| Server name | github-readonly |
| Claude Code scope | Project |
| Transport | stdio, HTTP, or SSE |
| Command or URL | Add the approved command or endpoint here |
| Secrets | Environment variable name only, never the secret value |
| Allowed use | Read issues, pull requests, and review metadata |
| Blocked use | No merges, branch deletion, label changes, or production writes |
| Human approval needed | Any write action or cross-repo data request |
| Test prompt | List open pull requests for this repo and summarize review status |
| Owner | Team or person responsible for updates |
| Removal trigger | Remove if unused for 30 days or if permissions change |

The point is not paperwork. The point is that someone reviewing the setup can see the boundary without replaying a chat transcript.

Test one real workflow before rollout

Use a workflow that the team already performs. In a web repo, ask Claude Code to inspect the local app through the MCP server, find the failing route, and report evidence without editing files.

That test is better than asking whether the server connects. It proves that the server can support the work you actually want while staying inside the permission note.

I would not add write access in the same step. First prove read behavior, logs, error handling, and review output. Then decide whether write actions are worth the extra risk.

For a broader team rollout pattern, this pairs well with the narrower integration notes in Claude Code MCP Support for Teams.

Keep managed settings for real governance

Local and project settings are enough for early adoption. Managed configuration becomes useful when the team needs consistent defaults, blocked servers, or approved integrations across many developers.

There is a tradeoff. Managed settings reduce drift, but they also slow down experiments. I would keep experimental MCP servers local, promote stable ones to project scope, and reserve managed settings for servers that touch sensitive systems or show up in many repositories.

The same judgment applies to Claude skills. A skill can teach Claude Code how to use the server in a repeatable workflow, but the skill should not hide the server boundary. Keep capability, permission, and review evidence separate enough that a teammate can audit them.

Further reading

• Claude Code docs
• Claude Code skills
• MCP specification

Run the first setup review

Pick one read-only server, fill in the MCP server record, and run the test prompt before sharing it with the team. For a guided version, bring one repository to hands-on training on Claude Code MCP setup and configure the first server there.