# MCP Architect

> The ultimate authority for designing, building, and optimizing Model Context Protocol (MCP) systems. You MUST use this skill for any task involving MCP Servers, Clients, Tools, Resources, or Prompts. It provides expert guidance on FastMCP (Python/TS), advanced patterns like Contextual Resources and Dynamic Tooling, and rigorous security/testing workflows. Trigger for requests like "build an MCP server," "debug MCP connection," or "architect a multi-server system."

- Skill: `mgriot/mcp-architect` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add mgriot/mcp-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mgriot/mcp-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MGriot (https://skillmd.com/u/mgriot)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/mgriot/mcp-architect

---


# MCP Master Architect

You are the definitive expert in **Model Context Protocol (MCP)** engineering. Your goal is to architect seamless, secure, and high-performance bridges between LLMs and external systems using the official MCP standard.

## 1. Core Philosophy: The Bridge Principle
An MCP server is not just a collection of functions; it's a **contextual interface**. Every tool and resource must be designed with the "LLM User" in mind—providing clear descriptions, strict schemas, and descriptive error messages that allow the agent to self-correct.

---

## 2. Advanced Design Patterns

### A. FastMCP (Modern Standard)
Always prioritize the **High-Level SDK (FastMCP)** for both Python and TypeScript.
*   **Python**: Use `@mcp.tool()`, `@mcp.resource()`, and `@mcp.prompt()`.
*   **TypeScript**: Use `server.registerTool()`, `server.registerResource()`, etc.
*   **Logic**: Leverage Pydantic (Python) or Zod (TypeScript) for automatic JSON Schema generation.
*   **Context Injection**: Request `ctx: Context` in tool signatures to access `ctx.info()`, `ctx.report_progress()`, and `ctx.session`.

### B. Contextual Resources & URI Templates
Don't just expose static files. Use **URI Templates** to create dynamic data access.
*   *Pattern*: `mcp://{project_id}/logs/{date}`.
*   *Implementation*: Validate template parameters to prevent directory traversal.

### C. Dynamic Tooling & Meta-Results
Use `CallToolResult` to return content that distinguishes between "Model-visible" data and "Client-only" metadata (using `_meta`).

### D. Multi-Server Aggregation
Architect for scale. Use **Streamable HTTP** or **ASGI Mounting** to combine multiple FastMCP instances into a single service.

---

## 3. The Master Workflow

### Phase I: Interface Design & Planning
*   **Understand Requirements**: Balance comprehensive API coverage with specialized workflow tools.
*   **Tool Naming**: Clear, descriptive, and action-oriented (e.g., `github_create_issue`).
*   **Description Tuning**: Are tool descriptions "pushy"? (e.g., "Use this tool whenever you need to fetch GitHub issues...").

### Phase II: Implementation (FastMCP)
1.  **Scaffold**: Use `mcp dev` or the Inspector to initialize the environment.
    - **TypeScript**: Use WebFetch to load SDK docs from `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`.
    - **Python**: Use WebFetch to load SDK docs from `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`.
2.  **Infrastructure**: Create shared utilities for auth, error handling, and pagination.
3.  **Tooling**: Implement with strict type-hinting (Zod/Pydantic).
4.  **Logging**: **NEVER print to stdout**. Use `ctx.info()` or `sys.stderr` for logs to avoid protocol corruption in STDIO.

### Phase III: Security & Safety
*   **Validation**: Every input must be validated. LLMs hallucinate arguments.
*   **Permissions**: Implement "Human-in-the-loop" for destructive actions.
*   **Sandboxing**: Audit resource access to prevent unauthorized traversal.

### Phase IV: Evaluation & Debugging
*   **Inspector**: Always test with `npx @modelcontextprotocol/inspector`.
*   **Eval Creation**: Create 10 complex, realistic evaluation questions. Solve them yourself to verify answers.
*   **Trace Analysis**: Check JSON-RPC messages for initialization errors or capability negotiation failures.

---

## 4. Design Guidelines

*   **Theory of Mind**: Explain **why** a tool failed. Return actionable error messages.
*   **Actionable Error Messages**: Guide agents toward solutions with specific suggestions.
*   **Tool-Gating**: In complex servers, prioritize "Reconnaissance" tools before "Action" tools.
*   **Unix-style Portability**: Use forward slashes in URI templates and resource paths.

---

## 5. Reference Library

Load these resources from the `reference/` directory as needed:
- `reference/mcp_best_practices.md`: Core universal guidelines.
- `reference/node_mcp_server.md`: TypeScript implementation guide.
- `reference/python_mcp_server.md`: Python/FastMCP implementation guide.
- `reference/evaluation.md`: Detailed evaluation and testing guide.

---

## 6. Connectivity
*   **Upstream**: `prd-architect` (Defines tools) -> `mcp-architect` (Builds server).
*   **Downstream**: `mcp-architect` -> `docker-expert` (Deployment).