Configure MCP in Claude Code: Local, Project and User Scopes

Configure MCP in Claude Code: Local, Project and User Scopes

To configure MCP in Claude Code, you pick a scope when you add the server: local (only you, only in that project), project (a .mcp.json file that is versioned and shared with the team) or user (only you, across all projects). The practical rule is to version only the structure of the configuration at project scope and keep secrets out of the repository by using environment variables.

This guide follows the official Claude Code documentation on MCP and separates what the documentation states from what is our implementation recommendation. Command names and file paths can change between versions, so check the current documentation before you standardize anything for the team.

Key takeaways

• Local scope is the default when you add a server: it stays private to you and applies only to the project you are in.
• Project scope writes a .mcp.json file at the root of the repository, designed to be versioned and shared.
• User scope makes the server available in all of your projects without sharing it with anyone.
• Credentials should never go into .mcp.json as plain text: use environment variable expansion and let each person supply their own value.
• Project servers require explicit approval before they run. That is a useful barrier, not an annoyance to work around.

What MCP solves and why scope matters

The Model Context Protocol is an open standard for connecting AI applications to external tools and data sources. In the official MCP introduction, the idea is that a server exposes capabilities (read a ticket, query a database, open an issue) and the client, in this case Claude Code, uses them when the task calls for it.

Scope answers a management question, not just a technical one: who sees and who uses this access? A server that reads your internal ticketing system may be useful to the whole team. A server that points to a personal test account, or that uses your own token, should not go into the repository. Getting the scope wrong usually causes one of two problems: a configuration that only works on one person's machine, or a credential that ends up in a commit.

The three scopes and where each one lives

The official documentation describes three scopes. It is worth memorizing how each behaves.

• Local: this is the default. The server is available only to you and only in the current project. The configuration is stored in the ~/.claude.json file, tied to the project path. Use it for experiments, personal credentials and sensitive servers that are still under evaluation.
• Project: the server is written to a .mcp.json file at the root of the repository. This file is designed to go into version control, so everyone who clones the project gets the same list of servers.
• User: the server is available to you in every project. It is also stored in ~/.claude.json and is not shared. Use it for personal utilities you want everywhere.

When the same server name appears in more than one scope, the documentation gives an order of precedence: local first, then project, then user. In practice, this lets one person override locally, for example, the address of a test server without changing what the team versioned.

To choose the scope, you use the scope option in the add command. A general example: claude mcp add --transport http server-name --scope project https://server-address. Options come before the server name, and for local stdio servers the server command comes after a separator. Check the exact syntax on the MCP page of the Claude Code documentation.

Which scope should you choose? A decision guide

Ask these questions, in order, for each server you plan to add:

• Does the server depend on a personal credential, such as an individual token? Use local or user, never project.
• Is the server useful only for one specific repository, and does the whole team need it set up the same way? Use project.
• Do you want the server in all of your repositories, but nobody else needs it? Use user.
• Are you still evaluating the server and not sure you trust it? Use local until the evaluation is done.
• Does the server access personal data of customers or employees? Start in local with read-only access, and only promote it to project after review by whoever is accountable for LGPD compliance in your company.

The last item deserves attention. A server shared at project scope becomes a team standard, and standards spread. If it touches personal data, the decision is no longer only an engineering one. For the regulatory framing, see LGPD and artificial intelligence: what companies should do.

How to version team configuration without exposing credentials

The central point of project scope is that .mcp.json goes into Git. Everything in it must therefore be safe for anyone with access to the repository, today and in future history. A committed secret is a leaked secret, even if you delete it later.

The official documentation supports environment variable expansion in .mcp.json, using curly braces preceded by a dollar sign, and also a form with a default value. This works in fields such as command, arguments, the server's environment variables, URL and headers. The result is a file that describes where to connect and how to authenticate, without containing the secret value itself.

The practices we recommend, based on implementation experience and not on the official documentation:

• Version .mcp.json with variable references only, never with the value.
• Document in the README which variables each person must set and where to get the value, without putting the value there.
• Use a secrets manager or the company password vault to distribute tokens, and prefer one token per person with the least privilege possible.
• Add local environment files, such as .env, to .gitignore, and confirm nobody has committed them before.
• Run a secret scan in CI or in a pre-commit hook so a slip is caught before the push.
• For remote servers with OAuth, prefer the flow where each person authenticates in their own client (the /mcp command inside Claude Code shows the status and lets you authenticate) instead of sharing a team token. To understand the flow, Google's OAuth 2.0 overview is a good neutral reference.

For storage and rotation of keys, see Managing API keys and secrets for AI agents: storage and rotation.

Step by step: setting up MCP for your team

A simple sequence you can complete in an afternoon for a first server:

• Step 1: define the goal. Write in one sentence which task the server will support, for example, checking an order status to debug an integration.
• Step 2: audit the server before installing it. Check who maintains it, which tools it exposes and which permissions it asks for. There is a checklist in How to audit an MCP server before installing it at your company.
• Step 3: add it at local scope, with a test credential and read-only access. Use the claude mcp add command and confirm with claude mcp list and claude mcp get.
• Step 4: test inside Claude Code with the /mcp command, checking the connection status and which tools appear.
• Step 5: adjust permissions. Define which of the server's tools Claude Code can use without asking and which require confirmation. The guide to Claude Code security: permissions, sandbox and secrets covers this control in detail.
• Step 6: promote to project. Add the server with project scope, replace any sensitive value with an environment variable and review the .mcp.json diff the way you would review code.
• Step 7: communicate and record. Tell the team, update the README with the required variables and note who approved the server and when.
• Step 8: review periodically. Remove unused servers with claude mcp remove and rotate tokens on a defined schedule.

What happens when someone clones the repository

When a person opens a project that has a .mcp.json, Claude Code asks for approval before using the project servers, according to the documentation. This exists because a versioned file can be changed by any contributor, and an MCP server can run commands on the machine of whoever uses it.

Treat this prompt as part of your review process. Two practical consequences:

• Changes to .mcp.json should go through a pull request reviewed by someone responsible for security or platform, like any change that executes code.
• If someone approved or rejected a server and wants to revisit the decision, the documentation describes the claude mcp reset-project-choices command to reset those choices.

The risk of instruction injection through content returned by tools also exists. OWASP's guidance on preventing prompt injection helps you think through that vector, and OWASP's authorization cheat sheet reminds you of the core principle: give each identity only the access it needs.

Illustrative scenario: a team of six

Illustrative scenario: a software company with six developers wants Claude Code to consult the internal documentation of an API. Separately, one developer wants to test a database server against a staging database.

The documentation server uses no personal data and serves everyone. After an audit, it goes into project scope, with the address in .mcp.json and the token referenced through an environment variable. Each person sets the variable with their own token, issued with read-only permission.

The database server stays at local scope for the developer who is testing it, pointing only to staging and using a read-only database user. If after a week the team decides it is worth sharing, the group reviews which tables it reaches, confirms there is no real personal data and only then proposes the change to project scope through a pull request.

The result is a shared configuration that carries no secrets and an experiment that does not contaminate the repository.

How we apply our method to MCP adoption

The method we use in AI projects fits well here. Map: list which team tasks depend on external context and what the current process is. Limit: choose the smallest set of servers, with read access and narrow scope. Pilot: start with one server and one real workflow, with usage logging and an agreed success criterion, in the style of How to measure an AI automation pilot. Hand over: give the team the documented configuration, with owners for review and rotation, and decide whether to expand, adjust or stop.

For the broader adoption context, see Claude Code for teams: an adoption guide with controls.

Frequently asked questions

What is the default scope when I add an MCP server in Claude Code?

The default is local scope, which keeps the server private to you and limited to the current project. To share it with the team, you must explicitly specify project scope when adding it. To have the server in all of your projects, specify user scope.

Can I put the token directly in .mcp.json if the repository is private?

It is not recommended. Access to private repositories changes over time, and they get cloned, copied to other environments and keep their history. Use the environment variable expansion described in the documentation and distribute the values through a secrets vault.

What happens if the same server exists in more than one scope?

The documentation indicates precedence: local scope wins over project, which wins over user. This lets you override an address or parameter locally without changing the team's file, but it is best to avoid duplicate names so nobody gets confused.

Do I need an MCP server for every system in the company?

No. Start with the workflow that depends most on external context and evaluate whether a direct API, a webhook or an MCP server fits better, as we discuss in How to integrate AI with your CRM: API, webhooks or MCP. If the system is internal, consider building the server starting with read-only access, as in How to build an MCP server for internal systems: read-only first.

Sources

• Claude Code: conectar ferramentas via MCP (documentação oficial)
• Model Context Protocol: introdução
• OWASP: guia de autorização
• OWASP: prevenção de prompt injection