The problem
An MCP server exposes a tool named search. Its description simply reads: "searches data." When deciding whether to invoke this tool, the model is forced to guess: searches what? Using what query syntax? What format is returned when zero records match? Without explicit answers in the tool description itself, the model frequently misroutes requests or generates invalid parameter types — with each hallucinated invocation burning an entire round-trip turn on error recovery.
The Model Context Protocol (MCP) solves a structural scalability challenge: without a shared standard, integrating a client (such as Claude Code or an agent runtime) with backend capabilities (databases, internal enterprise APIs, filesystem layers) requires bespoke point-to-point glue code. MCP standardizes this boundary, decoupling the capability provider (the server) from the capability consumer (the host). However, this decoupling only succeeds if the server interface is engineered with precision — which is where most architectural vulnerabilities occur.
Tool descriptions constitute the real API interface
A poorly architected MCP tool is rarely one with runtime execution bugs — it is one whose semantic description fails to provide the model with sufficient context to determine when and how to invoke it. A robust description must specify:
- What the tool does in concrete domain terms (not "searches data", but "searches active support tickets by customer ID or title keywords")
- Required versus optional arguments, along with expected formats and constraints
- Return schemas, including explicit empty-state definitions
- Relevant operational boundaries (rate limits, read-only vs. write scopes, side effects)
This is not documentation for human engineers — it is the machine-readable specification the model evaluates during tool selection. A vague description behaves like a function without type signatures: it succeeds only by coincidence.
Configuration scope: project-level vs. user-level
MCP defines explicit tiers for server configuration, with direct implications for security, maintainability, and team collaboration:
- Project configuration (
.mcp.json, versioned in git): Reserved for servers that the entire engineering team must share uniformly — such as an integration with a staging database. Because it is committed to source control, configuration changes undergo pull request reviews. - User or local configuration (
~/.claude.json): Intended for personal developer tools or experimental servers undergoing prototyping before broad team rollout.
Placing an experimental, unvalidated MCP server into a versioned .mcp.json propagates runtime instability to every developer on the team. Conversely, locking a mission-critical team server inside an individual's local ~/.claude.json breaks CI pipelines and teammates' environments. Incorrect configuration scoping alone is sufficient to render a scenario solution invalid.
Secrets utilized by MCP servers (such as API tokens) must never be hardcoded into versioned configuration files. The universal standard uses environment variable expansion (such as ${GITHUB_TOKEN}), ensuring credentials stay outside source control.
Descriptions and tool results as an attack surface
External or third-party MCP servers (outside your trust boundary) can return tool descriptions or execution payloads containing adversarial prompt injection attacks designed to hijack model behavior. Treating all third-party MCP tool descriptions and result payloads as untrusted data — and never as privileged system instructions — is an architectural requirement for secure integrations. This is especially critical before promoting any third-party server into project-level configuration.
Exposing resources instead of repetitive tool invocations
When an MCP integration exposes a large, relatively static catalog (such as a database schema or product category taxonomy), exposing it as an MCP resource rather than requiring iterative tool invocations significantly optimizes token consumption and latency. The model can inspect the resource directly in a single pass.
Put it into practice
In this lesson's lab, you will build an MCP tool contract validator: given a tool definition payload, it evaluates whether the description satisfies minimum specification standards (concrete purpose, parameter types, return contracts) and scans tool output streams for embedded instruction injection patterns.