AnthropicClaude Certified Architect – Professional2026-103.7 Evaluate connection protocols and select the appropriate integration mechanism (MCP, API/CLI, agent-to-agent)
Keep mediated calls in application code
Completed by the knowledge check
Learning objective
Choose direct API or custom tools when the application must mediate calls or apply custom logic, and CLI tools when agents work in shells with mature command-line interfaces.
Core idea
For an architect choosing between application code and a shell integration, the deciding factor is which interface can enforce the required operation with the least additional machinery. Application-owned tool loops and unattended-run controls establish execution; the decision here is where custom business behavior belongs and when an existing command is already the right adapter.
Choose a direct tool when the application must interpret the request, verify business state, and mediate a backend call. Choose an established CLI when the agent already works in a shell and the executable provides a suitable, supported interface. Neither choice eliminates authorization or acceptance checks, and neither is determined solely by the number of clients.
How it works
Put mediation before execution
A Messages API custom tool runs in your application, so it can mediate between the model-facing operation and several backend calls. See 1.2.2 for executor-side authorization and business-state checks; here the architectural question is whether a separate MCP service adds useful reuse or merely relocates an application-specific adapter.
Mediation is valuable when the model-facing operation combines backend results using application-specific logic. A handler can obtain both responses, reconcile their identifiers, and return one result through the client-tool interface. Moving that handler behind a remote MCP endpoint would add a network dependency without removing the combination logic; the extra boundary earns its cost only when consumers can reuse that operation.
The handler sits between the model-facing operation and several backend calls, and returns one result.
If mediation depends on application-only state or a result combination no other host needs, keeping it in the application avoids another deployment and compatibility surface. Revisit that placement when several hosts need the same operation, rather than treating a protocol wrapper as the default.
Share implementation without adding a protocol service
A direct tool can call a shared domain service or reusable library. A second consumer does not automatically require MCP. Ask whether you need a portable, discoverable host-facing contract, or whether consumers can already use a controlled application interface.
If three internal applications share the same refund service but intentionally expose different operations to their users, sharing the backend invariant may be sufficient. If several independent MCP hosts need to discover and invoke the same capability, an MCP server can reduce host-specific adaptation; see 3.7.2. Consumer count is a signal to investigate reuse, not a universal migration threshold.
The Agent SDK registers custom tools through an in-process MCP server, but a handler can still call your API directly. “Custom tool” and “MCP” are not exclusive labels: registration does not decide where backend mediation belongs.
Reuse mature commands in their working environment
Anthropic’s Claude Code best-practices page describes CLIs as the most context-efficient way to interact with external services and recommends learning unfamiliar commands through --help. Its gh example contrasts an installed CLI with unauthenticated GitHub API requests that often hit rate limits. For an architect, this makes an established executable worth comparing with an MCP server’s tool definitions before introducing another adapter.
Evaluate the actual command rather than assuming maturity from its name. Does the selected version provide the operation you need? Can it run without a terminal interaction in this environment? Can the calling job distinguish a command failure from a valid empty result? Which account does it use, and what backend permission does that account carry? These are acceptance questions for the chosen executable, not guarantees supplied by Claude Code.
Claude Code permission rules control shell tool use. An illustrative allow rule such as Bash(warehousectl inspect *) pre-approves matching calls; an ask rule can require review for a matching mutation. Rules are enforced by Claude Code rather than by the model. They still do not replace the warehouse service’s authorization checks or prove that every command with a matching prefix has acceptable business effects.
For unattended jobs, use claude -p with the established permission policy, then test the executable’s credentials, interaction requirements, result handling, and job limits in that environment. A blanket claim that CLI tools require a nearby human would exclude supported programmatic Claude Code workflows.
Key distinctions and trade-offs
Compare these choices by the work they remove and the obligations they retain:
| Choice | Useful when | Responsibility you retain |
|---|---|---|
| Direct Messages API custom tool | Application needs exact control before dispatch | Executor policy, backend call, tool-result handling |
| Agent SDK custom handler | Agent harness is useful, with application-specific operations | Handler policy and SDK registration/configuration |
| Established CLI through Claude Code | Shell workflow already has a suitable executable | Runtime identity, command version, permissions, result interpretation |
| Shared MCP service | Compatible hosts need the same discoverable capability | Server operation, authorization, client compatibility |
A direct integration can reduce deployment components while increasing application-specific code. A CLI can reduce adapter code and tool-definition context while increasing dependence on the environment; the documented context-efficiency benefit is not a guarantee of lower latency. A shared server can centralize behavior while creating a shared service dependency. Measure the actual path; these are architectural tendencies, not guaranteed latency rankings.
For every choice, preserve an explicit outcome when policy denies execution or required input is missing. A tool request that was never executed must not be represented as a successful backend action. The handler’s result and the application’s acceptance record should agree about what happened.
Architecture / decision scenario
A financial-services onboarding application must return a sanctions-screening summary within three seconds. It must combine two backend screening results under the same customer revision before Claude receives either result. The team also runs a nightly repository audit using a mature internal CLI with a tested non-interactive mode and machine-readable output.
An engineer proposes wrapping both capabilities in remote MCP servers so they look uniform. The application architect retains an illustrative direct screen_customer tool whose handler combines the two screening responses, preserves their source identifiers, and returns an unresolved outcome if they refer to different customer revisions. The measured prototype meets the three-second target. A remote wrapper adds deployment and failure handling without removing the required result mediation.
The audit retains its CLI through Claude Code because the shell environment already contains the approved executable and audit account. The job owner tests credential expiry and command failure, configures scoped Bash permission rules and unattended-run controls, and accepts results only when the required audit artifact is present. There is no need to recreate the command’s interface as a separate server solely for this job.
The tempting alternative promises a consistent protocol. The deciding constraints are the screening summary’s application-specific combination and the audit’s mature shell interface. The architect revisits MCP if additional compatible hosts need a shared capability contract, rather than treating either initial choice as permanent.
Common exam traps
- Treating a valid tool input as proof of authorization.
- Reimplementing a backend invariant independently in every prompt or tool handler.
- Assuming a second application automatically makes MCP necessary.
- Calling an SDK in-process custom tool a separately operated remote service.
- Accepting a shared administrator login merely because the CLI command works.
- Rejecting all unattended CLI workflows instead of testing the actual environment.
What to remember
Use application mediation for business-sensitive calls and custom logic. Reuse a mature CLI where its execution environment and output contract fit the agent’s work. Choose a shared protocol when it solves a real host-integration problem, and keep policy enforcement with the component that performs the operation.
Knowledge check
An onboarding application must return a sanctions-screening summary within three seconds. The summary combines two screening backends’ results, and both must refer to the same customer revision before Claude sees either. No other host needs the operation. Which design meets the requirement with the least additional machinery?
Three internal applications share one refund service whose invariant must hold for every refund. Each application deliberately exposes different refund operations to its users, and none needs a discoverable host-facing contract. A reviewer argues that having more than one consumer now requires an MCP server. What should the architect do?
A nightly repository audit runs through Claude Code and uses a mature internal CLI with a tested non-interactive mode and machine-readable output. No one is present when it runs. A reviewer says that CLI tools need a nearby human, so the audit must be rebuilt as an MCP server. What should the job owner do?
claude -p with the existing shared administrator account and broad Bash accessclaude -p with scoped Bash rules and a tested audit accountclaude -p , so the claim that CLI tools need a nearby human is false. The owner keeps the mature executable, scopes Bash permission rules, and tests the audit account’s credentials, the non-interactive mode and failure handling in that environment. A shared administrator login trades away the account boundary because the command happens to work.A Claude Code allow rule, Bash(warehousectl inspect *), pre-approves inspection commands for an operations team. A security reviewer asks whether the warehouse service can now drop its own authorization check for those calls. What is the correct answer?
References
- Anthropic, Define tools
- Anthropic, Give Claude custom tools
- Anthropic, Best practices for Claude Code
- Anthropic, Configure permissions
- Anthropic, CLI reference