MCP Server Strategist

Full-lifecycle MCP server architecture agent covering design, implementation, transport configuration, and production deployment.

When to Use This Agent

Choose this agent when you need to:

• Architect a new MCP server from requirements through to production deployment
• Design tool interfaces with proper JSON Schema validation and annotations
• Implement dual-transport support for stdio and Streamable HTTP endpoints
• Optimize server performance with connection pooling, caching, and batching

Consider alternatives when:

• You need to find existing servers in registries (use Guide MCP Navigator)
• Your focus is on security hardening an existing server (use MCP Security Auditor)

Quick Start

Configuration

Copy
name: mcp-server-strategist
type: agent
category: mcp-dev-team

Example Invocation

Copy
claude agent:invoke mcp-server-strategist "Design an MCP server for a product catalog API with search, CRUD, and inventory tools"

Example Output

MCP Server Architecture: product-catalog-mcp
=============================================

Tools Designed: 7
  - search-products (read-only, completions enabled)
  - get-product (read-only)
  - create-product (idempotent)
  - update-product (destructive)
  - delete-product (destructive, requires approval)
  - check-inventory (read-only)
  - adjust-inventory (destructive)

Transports: stdio, Streamable HTTP (/mcp endpoint)
SDK: @modelcontextprotocol/[email protected] (TypeScript)
Session: CSPRNG IDs with 15-min timeout
Completions: product name and category suggestions

Generated files:
  src/server.ts        - Server initialization and transport setup
  src/tools/catalog.ts - Product CRUD tool handlers
  src/tools/search.ts  - Search with completion support
  src/schemas/         - JSON Schema definitions for all inputs
  Dockerfile           - Multi-stage production build

Core Concepts

Server Lifecycle Overview

Aspect	Details
SDK	@modelcontextprotocol/sdk >= 1.10.0 (TypeScript) or Python
Specification	MCP 2025-06-18
Endpoint	Single /mcp path handling GET and POST
Tool Design	JSON Schema inputs, annotations, completion support
Transports	stdio for local, Streamable HTTP for remote
Deployment	Containerized with multi-stage Docker builds

Server Component Architecture

┌─────────────┐     ┌─────────────┐
│  Transport   │────▶│  Request     │
│  Layer       │     │  Router      │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Session     │────▶│  Tool        │
│  Manager     │     │  Handlers    │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
language	enum	"typescript"	Implementation language: typescript or python
transports	string[]	["stdio","http"]	Transport layers to implement
enableCompletions	boolean	true	Implement completion/complete endpoint for argument suggestions
enableBatching	boolean	true	Support JSON-RPC batch requests over HTTP
sessionTimeout	number	900	Session inactivity timeout in seconds

Best Practices

1. Design High-Level Tools Over Granular API Wrappers Resist the urge to create one MCP tool per REST endpoint. Instead, group related operations into intentional, high-level tools that accomplish meaningful tasks. This reduces token usage and improves agent reasoning about available capabilities.

2. Implement Completions for Every Enumerable Argument When a tool argument accepts values from a known set (categories, statuses, region codes), implement the completions capability. This allows AI clients to present accurate suggestions rather than guessing, dramatically reducing invocation errors.

3. Route All Diagnostic Output to stderr On stdio transports, stdout is exclusively for JSON-RPC protocol messages. Any log statement, debug print, or library warning that reaches stdout corrupts the message stream. Configure your logging framework to target stderr explicitly.

4. Use Multi-Stage Docker Builds for Production Separate build dependencies from runtime dependencies. The build stage compiles TypeScript and installs dev dependencies, while the production stage copies only compiled output and production node_modules. This reduces image size by 60-80%.

5. Validate Inputs Before Processing, Always Even though the MCP SDK validates JSON Schema on tool inputs, add application-level validation for business rules. Schema validates structure; your code validates semantics like date ranges, permission scopes, and cross-field dependencies.

Common Issues

1. Server starts but clients cannot discover any tools The tools capability is not declared in the server's initialize response. Ensure your server constructor explicitly registers the tools capability and that each tool handler is bound before the server starts accepting connections.

2. Streamable HTTP endpoint returns 404 on client connections The server is exposing tools at a custom path instead of the standard /mcp endpoint. MCP clients expect a single /mcp path handling both GET (for SSE streaming) and POST (for JSON-RPC requests). Verify your HTTP routing configuration.

3. Connection pooling exhaustion under concurrent load The server creates a new database connection per tool invocation without pooling. Configure a connection pool with appropriate min/max settings and idle timeouts. For PostgreSQL, use pg-pool with a max of 20 connections and 30-second idle timeout.