MCP Server Architect Helper

Your expert agent for designing, building, and deploying Model Context Protocol (MCP) servers — covering the full server lifecycle from design through production deployment with deep knowledge of the MCP specification.

When to Use This Agent

Choose MCP Server Architect Helper when:

• Designing MCP server architecture for new tools and integrations
• Implementing MCP tools, resources, prompts, and transport layers
• Building production-grade MCP servers with proper error handling and security
• Deploying MCP servers and configuring them with Claude Code or other clients
• Troubleshooting MCP server connectivity, protocol errors, or performance issues

Consider alternatives when:

• You need Kotlin-specific MCP servers — use the Kotlin MCP Expert agent
• You need PHP-specific MCP servers — use the PHP MCP Expert agent
• You need general API design (not MCP) — use an API navigator agent

Quick Start

Copy
# .claude/agents/mcp-architect.yml
name: MCP Server Architect Helper
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: MCP server architect for designing tools, resources, transports, and production-grade MCP deployments

Example invocation:

claude "Design an MCP server that exposes our internal wiki as resources, provides a search tool, and includes prompt templates for common wiki operations"

Core Concepts

MCP Architecture

┌─────────────────────────────┐
│        MCP Client           │
│   (Claude Code, IDE, etc.)  │
└─────────┬───────────────────┘
          │ MCP Protocol (JSON-RPC)
          │
┌─────────┴───────────────────┐
│      Transport Layer         │
│   stdio │ SSE │ WebSocket    │
├─────────────────────────────┤
│       MCP Server             │
│  ┌────────┬────────┬──────┐ │
│  │ Tools  │Resources│Prompts││
│  └────────┴────────┴──────┘ │
├─────────────────────────────┤
│    Backend Services          │
│  Database │ APIs │ Files     │
└─────────────────────────────┘

MCP Components

Component	Purpose	Example
Tools	Actions the AI can perform	query_database, send_email, create_ticket
Resources	Data the AI can read	file://config.yaml, db://users/schema
Prompts	Reusable prompt templates	analyze_logs, review_code, explain_error
Transport	Communication layer	stdio (local), SSE (remote), WebSocket (bidirectional)
Sampling	Server requests AI completion	Ask the client LLM to analyze data

Configuration

Parameter	Description	Default
transport	Transport type (stdio, sse, websocket)	stdio
language	Implementation language (typescript, python, kotlin)	typescript
auth_method	Authentication for remote servers (none, token, oauth)	none
logging	Log level and destination	stderr
max_request_size	Maximum request payload size	10MB

Best Practices

1. Design tools with clear, specific names and descriptions. The LLM client uses tool names and descriptions to decide when to call them. search_wiki(query) with description "Search the internal wiki for articles matching the query" is better than search(q) with no description.

2. Use resources for read-only data, tools for actions with side effects. Resources should be idempotent and safe to read repeatedly. Tools that modify state (create, update, delete) should include confirmation in their description and validate inputs strictly.

3. Return structured data, not just strings. When tools return results, use structured formats (JSON, tables) that the LLM can reason about. A list of key-value pairs is more useful than a paragraph of prose when the LLM needs to extract specific information.

4. Handle errors gracefully with descriptive messages. When a tool fails, return an error that explains what went wrong and suggests a fix. "Database connection refused at localhost:5432 — ensure PostgreSQL is running" is actionable. A raw stack trace is not.

5. Keep stdio transport output clean. When using stdio transport, all stdout is MCP protocol data. Application logging must go to stderr or a file. Any stray console.log or print statement will corrupt the protocol stream and break the client connection.

Common Issues

Client doesn't see the server's tools after startup. The server must correctly handle the initialize request and respond with its capabilities before tools/list works. Verify the initialization handshake completes and that tools are registered before the server reports ready.

Remote MCP server has high latency. SSE transport over the internet adds network latency to every tool call. For performance-critical tools, consider caching results, batching operations, or running the MCP server closer to the data source it accesses.

Tool schema validation rejects valid inputs. Strict JSON Schema validation may reject inputs that are semantically valid but structurally different (extra whitespace, different key ordering, missing optional fields). Test tool schemas with various input formats and loosen validation where appropriate.