CapabilityAtlas CapabilityAtlas
Sign In
search
Integration & Operations • Fundamentals

MCP Design & Integration

Model Context Protocol: server design, tool descriptions, error responses, interoperability.

Fundamentals Mastery Build Market
terminal Practice

MCP Design & Integration — Competence

What an interviewer or hiring manager expects you to know.

Core Knowledge

  • What MCP is and why it exists. Model Context Protocol (Anthropic, open standard) is the standardized interface between AI agents and external tools/data sources. Before MCP, every agent framework (LangChain, LlamaIndex, CrewAI) defined its own tool interface — tools built for one framework didn’t work in another. MCP provides: a universal tool definition schema, a client-server architecture (AI host → MCP client → MCP server → external system), and a standard for discovery, invocation, and error handling. It’s the USB-C of AI tool integration — one protocol, many implementations.

  • MCP architecture. Three components: Host (the AI application — Claude Code, Claude Desktop, an IDE), Client (manages connections to servers, routes tool calls), Server (exposes tools, resources, and prompts to the client). Servers are lightweight processes that wrap external APIs, databases, or local functionality. The agent sees tools from all connected servers simultaneously. Communication uses JSON-RPC over stdio (local servers) or HTTP with SSE (remote servers). Know the distinction: local servers run as child processes, remote servers run over the network.

  • Tool definition quality. Tool descriptions are the PRIMARY mechanism Claude uses for tool selection — not supplementary metadata. A tool with description “Gets data” will be misrouted constantly. Good descriptions include: what the tool does (primary purpose), what inputs it expects (formats, constraints), example queries it handles well, edge cases and limitations, and explicit boundaries (when to use THIS tool vs. similar tools). The exam tests this directly: two tools with overlapping descriptions cause misrouting; the fix is better descriptions, not routing classifiers or tool consolidation.

  • MCP server configuration. Project-level: .mcp.json in the repo root (version-controlled, shared with team). User-level: ~/.claude.json (personal, NOT shared). Environment variable expansion: .mcp.json supports ${GITHUB_TOKEN} syntax to keep credentials out of version control. Server types: command (stdio-based local server — a process you spawn) and url (HTTP+SSE remote server). Know the scoping: project-level for team tools, user-level for personal tools.

  • Community servers vs. custom builds. The MCP ecosystem has 100+ community servers for standard integrations: GitHub, Jira, Slack, PostgreSQL, Google Drive, Notion, Linear, Sentry, Brave Search, filesystem, and many more. Decision rule: use community servers for standard integrations (faster, maintained by the community, battle-tested). Build custom only for team-specific workflows that community servers can’t handle (proprietary APIs, custom business logic, internal databases). The exam tests this: building a custom Jira MCP server when a community one exists is the wrong answer.

  • MCP resources and prompts. Beyond tools, MCP servers can expose: Resources (content catalogs — issue summaries, documentation hierarchies, database schemas — gives agents visibility into available data without requiring exploratory tool calls) and Prompts (reusable prompt templates that servers provide to the host). Resources are the “what data exists” layer; tools are the “how to interact with data” layer. Exposing a database schema as a resource lets the agent understand the data model before making queries.

  • Structured error responses. MCP defines the isError flag for communicating failures back to the agent. Design error responses with: error category (transient/validation/business/permission), isRetryable boolean, human-readable description, and partial results if available. Critical distinction: access failure (tool couldn’t reach the data source — consider retry) vs. valid empty result (tool queried successfully, found nothing — don’t retry, this IS the answer). Confusing these breaks recovery logic.

Expected Practical Skills

  • Configure MCP servers in .mcp.json. Set up 2-3 MCP servers (e.g., GitHub, filesystem, a database) with proper environment variable expansion for credentials. Verify tools are discovered by the host.
  • Write high-quality tool descriptions. Given two similar tools that cause misrouting, diagnose the description overlap and write differentiated descriptions that prevent selection confusion.
  • Implement a custom MCP server. Build a simple MCP server that wraps an internal API: expose 3-5 tools with clear schemas, implement structured error responses with error categories, and register it in .mcp.json.
  • Design tool distribution across agents. Given an agent system with 15+ tools, scope tools to specialized subagents (4-5 tools each). Ensure no agent has access to tools outside its role. Configure allowedTools restrictions.
  • Debug MCP tool selection issues. When an agent calls the wrong tool: read the tool descriptions from the agent’s perspective, identify the ambiguity or overlap, and fix the descriptions. Check system prompt for keyword-sensitive instructions that create unintended tool associations.

Interview-Ready Explanations

  • “Walk me through how you’d integrate external tools into an AI agent using MCP.” Identify the tools needed. Check the MCP community server registry — for standard integrations (GitHub, Jira, Slack, databases), use existing servers. For custom needs, build a server that wraps the API. Configure in .mcp.json with environment variable expansion for credentials. Write clear, differentiated tool descriptions (the agent reads these to decide which tool to use). Test tool selection: give the agent ambiguous queries and verify it picks the right tool. Scope tools per agent (4-5 per subagent, not 15+ on one agent). Add structured error responses so the agent can handle failures intelligently.

  • “How do you handle tool selection reliability when an agent has many tools?” Three levers: (1) Tool description quality — clear, specific, non-overlapping descriptions are the #1 fix for misrouting. (2) Tool scoping — limit each agent to 4-5 tools relevant to its role. A synthesis agent shouldn’t have web search tools. (3) tool_choice configuration — "auto" for general operation, "any" for guaranteed tool invocation, forced selection for mandatory first steps. Before adding routing classifiers or few-shot examples, fix descriptions and reduce tool count — those are lower-effort, higher-leverage.

  • “When would you build a custom MCP server vs. using a community one?” Use community when: the integration is standard (GitHub, Slack, databases), the community server is maintained and mature, and your requirements don’t need custom business logic. Build custom when: the API is proprietary (internal company systems), you need custom business logic (transform data before exposing to the agent), the community server lacks features you need, or security requirements prohibit using community code. Always evaluate community first — building custom when a maintained community server exists is wasted effort.

terminal Practice this skill Mastery arrow_forward