Model Context Protocol (MCP)
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) is a standardized communication framework designed to enable Large Language Models (LLMs) to interact seamlessly with external services, tools, and data sources. In this project, MCP is utilized to build "MCP Servers" that provide the AI agent with specialized capabilities—such as searching users, creating issues, or fetching real-time data—by exposing executable functions through a consistent interface. Sources: skill/mcp-builder/SKILL.md:5-10, skill/mcp-builder/reference/mcp_best_practices.md:5-10
The protocol ensures that the AI agent can discover available tools, understand their requirements through JSON schemas, and execute them with human-in-the-loop oversight. This architecture bridges the gap between static model knowledge and dynamic real-world environments. Sources: skill/mcp-builder/SKILL.md:15-20, skill/mcp-builder/reference/mcp_best_practices.md:135-140
Architecture and Design Principles
The MCP implementation follows an agent-centric design, focusing on workflows rather than simple API wrappers. The goal is to provide high-signal information while respecting the limited context windows of LLMs. Sources: skill/mcp-builder/SKILL.md:25-35
Core Components
| Component | Description |
|---|---|
| MCP Server | The backend service that hosts tools and resources, communicating via stdio or HTTP. |
| Tools | Executable functions with defined input schemas and semantic descriptions for LLM invocation. |
| Resources | Data endpoints exposed via URIs (e.g., file://documents/{name}) for static context. |
| Transport | The communication layer (Stdio, HTTP, or SSE) between the client and server. |
Sources: skill/mcp-builder/reference/node_mcp_server.md:10-50, skill/mcp-builder/reference/mcp_best_practices.md:15-30
Communication Flow
The following diagram illustrates the interaction between the User Interface, the AI Agent, and an MCP Server during a tool invocation.
Tool Development and Validation
Tools are the primary mechanism for interaction. Each tool must be registered with a unique name, descriptive metadata, and a strict validation schema. Sources: skill/mcp-builder/reference/node_mcp_server.md:55-70
Tool Structure and Annotations
Tools include hints that describe their behavior, allowing the agent to handle them safely:
- readOnlyHint: Indicates if the tool modifies the environment.
- destructiveHint: Warns of potential data loss or irreversible actions.
- idempotentHint: Confirms if repeated calls produce the same result.
- openWorldHint: Signals interaction with external systems.
Sources: skill/mcp-builder/SKILL.md:140-150, skill/mcp-builder/reference/mcp_best_practices.md:165-180
Input Validation with Zod
In Node/TypeScript implementations, Zod schemas are used to enforce runtime type safety and provide clear error messages to the agent.
const UserSearchInputSchema = z.object({
query: z.string().min(2).max(200).describe("Search string"),
limit: z.number().int().min(1).max(100).default(20),
response_format: z.nativeEnum(ResponseFormat).default(ResponseFormat.MARKDOWN)
}).strict();
Sources: skill/mcp-builder/reference/node_mcp_server.md:75-100
Best Practices and Constraints
To ensure reliability and context efficiency, MCP servers must adhere to strict operational standards.
Response Management
- Formatting: Servers should support
markdownfor human readability andjsonfor programmatic data processing. Sources: skill/mcp-builder/reference/mcp_best_practices.md:85-100 - Truncation: Large responses must be checked against a
CHARACTER_LIMIT(typically 25,000 characters) and truncated gracefully to avoid context overflow. Sources: skill/mcp-builder/reference/node_mcp_server.md:200-220, skill/mcp-builder/reference/mcp_best_practices.md:115-125 - Pagination: Tools that return lists must implement
limitandoffsetparameters, returning metadata likehas_more. Sources: skill/mcp-builder/reference/mcp_best_practices.md:105-115
Naming Conventions
| Environment | Naming Pattern | Example |
|---|---|---|
| Python | {service}_mcp | github_mcp |
| Node/TS | {service}-mcp-server | github-mcp-server |
| Tool Names | {service}_{action}_{resource} | slack_send_message |
Sources: skill/mcp-builder/reference/mcp_best_practices.md:15-25, skill/mcp-builder/reference/node_mcp_server.md:35-45
System Prompt Integration
The AI agent is instructed via the system prompt to utilize MCP tools for external integrations. It is strictly forbidden from writing its own code to handle these tasks, instead relying on the McpServer to bridge communication with services like Supabase or GitHub. Sources: apps/client/src/prompts/system_prompt.ts:400-450, Comprehensive.md:50-70
The Model Context Protocol establishes a robust foundation for building extensible AI features, ensuring that tool execution is safe, predictable, and context-aware. By following these architectural guidelines, developers can create high-impact workflows that empower the AI agent to solve complex real-world tasks. Sources: skill/mcp-builder/SKILL.md:250-260