A team can build an excellent MCP tool and still produce a bad Claude workflow by configuring that tool at the wrong scope. An assistant may discover an administrative server inside an ordinary project, inherit credentials that were intended for a different tenant, or prefer a vaguely described external tool over a faster built-in operation. These are not failures of protocol syntax alone. They are failures to decide which capabilities belong in which working environment.
For the Claude Certified Architect – Foundations exam, officially coded CCAR-F and also known here as CCA-F, MCP configuration belongs alongside tool-interface design. The protocol makes tools, resources and reusable prompts discoverable. It does not promise that every available tool is suitable for every task. Architects must decide what is installed, what is discoverable, what is authorized and what happens when a dependency fails.
Treat configuration scope as an exposure boundary
Imagine a consultant working across two client repositories. Each project requires a ticketing integration, but the tenants, permitted issue types and secrets differ. A user-wide MCP configuration that makes both ticketing servers available everywhere creates a greater chance of selecting the wrong target. A project-scoped configuration can make the relevant integration discoverable only in the repository that actually needs it.
Claude Code distinguishes configuration scopes, including local, project and user-level arrangements. Their exact storage details and commands can change as the product evolves, so a team should verify the documentation for the installed version rather than copying an old configuration file. The design question is stable: should this capability follow one developer, one checked-out project or a particular local environment?
Project-scoped configuration is appropriate for team-shared, reproducible integration declarations. A repository can explain that its tests depend on a documentation MCP server or a particular development ticketing endpoint, and teammates can inspect the same declared capability. Local configuration is useful when a tool address or credential belongs only to one machine and must not become part of shared project history. User-wide settings can suit genuinely general utilities, but such convenience should be weighed against exposing irrelevant tools inside sensitive repositories.
Scope does not equal authorization. A project-local server can still connect to a privileged remote database if the backing credentials are broad. A user-wide server can be narrowly read-only. Permission checks belong at the service boundary, while configuration scope determines where the capability is discoverable. Mixing these meanings leads architects to claim safety from a folder location that provides no actual security guarantee.
Keep .mcp.json reproducible without leaking secrets
A project may use a .mcp.json declaration to describe servers shared with the team. Consider a document-analysis repository that declares a read-only knowledge-base server. The configuration can identify the server command, arguments or endpoint and expected environment-variable names without embedding the credential value in version control. The underlying deployment or developer environment supplies that value through an approved secret-management mechanism.
Environment-variable expansion is convenient for choosing a different URL or token per environment, but it creates a second place to validate assumptions. If the variable is missing, a configuration may point to an unintended fallback or fail only after a user starts a task. A robust setup checks required variables early and reports an understandable configuration error rather than allowing the model to guess which server should have been present.
The distinction between variable names and secret contents deserves deliberate review. A sample configuration showing TICKETING_API_TOKEN as a required variable is useful; copying a real key into a README or prompt is not. Logs and error messages should not echo secrets back into the model context. The same rule applies to command-line arguments when they may be visible to other processes or diagnostic tools.
Version control introduces another risk: a team may merge a project configuration change that unexpectedly exposes a new write-capable server to everyone. Review MCP configuration with the same care given to dependency and permission changes. Identify the server operator, data classification, permitted actions, credential owner and incident-removal procedure. A working connection proves only reachability, not that the integration is approved for every user.
Configuration scope is a deliberate least-privilege choice
A shared project may need a read-only issue-tracker server so everyone can reproduce a development workflow. A developer’s local machine might additionally expose a private browser or test-data service. Publishing that private server configuration to the repository would make it discoverable in contexts where it does not belong; copying credentials into a shared .mcp.json would be worse. Put only nonsecret project-owned configuration into shared files, keep private scope and secrets in the supported user or environment configuration, and make every necessary permission explicit.
Tool descriptions are part of the selection interface, but not an authorization mechanism. A tool called manage_everything with a free-text argument invites confusion and excessive access even if the server is correctly configured. Prefer bounded operations with typed arguments and obvious success/failure reporting; enforce the caller’s identity at the backend. When a server provides overlapping capabilities with built-in tools, choose the simpler reliable path rather than forcing every operation through MCP for consistency’s sake.
Test the configuration from a clean checkout with no developer’s private credentials. Confirm which servers appear, which are intentionally absent and what happens when one is disabled. For a sensitive deployment, test that revoked access prevents new operations even when a stale session tries to resume. A reliable architecture specifies both capability discovery and emergency disablement; finding a tool in Claude’s list is not permission to use it for a privileged action.
Tool discovery should help Claude choose correctly
When a model sees several similar tools, selection quality depends partly on names, descriptions, input contracts and the current task. A support system that offers search_record, find_record, lookup_item, and read_item with nearly identical descriptions invites confusion. Adding more synonyms to the system prompt may merely transfer that confusion to another layer.
The stronger repair is to clarify each interface’s purpose. A tool for retrieving a customer by verified identifier should say exactly which identifiers it accepts and what scope it searches. A tool for text discovery should explain whether it performs fuzzy search or requires an exact key. Overloaded tools can be split when they conceal materially different permissions. Conversely, twenty one-line wrappers around the same harmless query might be consolidated so tool selection remains intelligible.
The application can also limit tool exposure per agent. A coordinator that delegates source retrieval to a research subagent need not grant the report-writing subagent permission to modify records. Reducing the available action surface improves both safety and selection accuracy. It should not be presented as a universal formula for “one tool per job”: the correct division depends on distinct operations, permissions and task needs.
tool_choice controls are useful when a workflow must require, forbid or constrain certain classes of tool use, depending on the currently supported API contract. Forced invocation is not a substitute for backend authorization. An architect should be able to explain why the application may require an extraction tool in one step while leaving tool choice automatic during an exploratory query. The latter allows genuine uncertainty to be resolved without inventing a rigid sequence.
The design of an MCP tool’s contract remains the best place to settle argument validation and privileges. Configuration determines how that tool is made available; description and choice policies determine when Claude is likely to request it.
Resources, tools and prompts do different work
MCP is often described as “giving Claude tools,” but tools are only one part of the interface. A resource can expose information such as a versioned specification or policy document; a tool can perform an action or fetch information with parameters; a prompt can offer a reusable interaction pattern. The distinctions affect how provenance and authority should be handled.
Consider a development assistant comparing a codebase with an engineering policy. A resource representing the approved policy version is not the same as an action tool that opens a production firewall rule. Treating both as generic pieces of text erases the consequence of an operation. A resource needs metadata such as origin and revision so users know what was consulted. An action tool needs request validation, an authorization decision and an execution receipt.
Prompts supplied by a server should not silently become higher-authority instructions merely because the server uses the MCP protocol. A prompt is a reusable asset whose trust must be evaluated in context. The application should not allow externally supplied prompt text to override protected policies, alter tool permissions or disguise user data as trusted system instructions.
Resource discovery also has practical performance implications. Dumping an entire manual into every Claude turn wastes context and obscures the question. A resource interface can expose precise locations, metadata and targeted retrieval so the model receives the material it genuinely needs. That information architecture supports accurate citations and manageable context size rather than maximizing the amount of text sent to the model.
Decide when a built-in tool is better
A Claude Code workflow already has access to built-in capabilities such as searching and reading files when those are permitted. Introducing an MCP server merely to wrap a local file search may add authentication, network dependencies and more confusing tool names without any improvement in outcome.
The sensible choice depends on where data resides and which permissions are needed. For exploring a local repository, the editor or built-in file tools are often the most direct path. For a read-only issue tracker, an MCP integration can make remote records accessible through a controlled interface. For a regulated customer database, an approved backend service must enforce tenant identity, purpose limitations and audit trails. The common task label “search” does not make these routes interchangeable.
There is also a difference between a discovery problem and an access problem. If Claude chooses the wrong tool because descriptions overlap, improve the descriptions or tool distribution. If it cannot read the intended source because the credentials lack permission, changing the prompt is not a legitimate fix. If the required source is unavailable, the assistant should report the missing evidence or request a human decision instead of using a vaguely related dataset to complete the answer.
An architect should therefore start with the least complicated useful path and add protocol integration when it creates a real capability, not for architectural fashion. Overengineering the interface can make a task more brittle while making a diagram look more enterprise-ready.
Make failures understandable to people and software
An MCP call may fail because the server is unavailable, the input is invalid, the user lacks permission or the business operation cannot be performed. A response that merely says “Operation failed” with no category and no next action causes the coordinator to improvise. It may repeat a forbidden request, interpret a missing value as a genuine empty result or overstate completion.
A useful error return distinguishes transient service failures from permanent validation failures, permission denials and ordinary business outcomes. In MCP contexts the isError signal and structured result content can communicate tool-level failure; API client tool-result contracts may use a different spelling or representation. Implementations should follow the specific protocol version rather than treating familiar flags as interchangeable.
For a customer lookup, “no account matches the supplied identifier” is a legitimate completed search result. “The customer service could not be reached” is an incomplete attempt. Those conditions should produce different user messages, retry policies and metrics. Permission denial must not be retried with a broader identity. An ambiguous write timeout should prompt a status check before any duplicate action is attempted.
Report errors with stable codes and short operational meaning, while keeping secrets and unnecessarily sensitive data out of the model’s next prompt. Errors are part of the public tool contract. Their quality affects whether the agent can make safe choices after an interruption.
Test the configuration as a system, not a screenshot
A configuration review is incomplete if it ends when the MCP server appears in the tool list. Test with the correct and incorrect project, a missing environment variable, an expired credential, an unauthorized operation, a failing server and a tool that intentionally overlaps another tool’s description. Record not just whether a tool was called but why it was selected and whether the application enforced permission at the backend.
For a team setting, verify that a fresh checkout gets the declared nonsecret configuration, that local secret injection works, and that one member’s private server is not silently exposed to others. For incident recovery, confirm that removing or disabling the server prevents further requests, including those from resumed sessions. When tools are shared across subagents, inspect whether each agent receives only the tools its task requires.
Finally, test the quality of the answer produced after the tool runs. It should contain information backed by actual returned data, identify uncertainties and avoid presenting a failed retrieval as a verified conclusion. The real purpose of MCP configuration in the CCAR-F architectural picture is not to produce a long list of connected servers. It is to make the right capabilities available to the right workflow under the right controls, with a traceable explanation of what happened.