PolyMCP Builder

Overview

Build production-ready MCP servers with PolyMCP. This skill provides fast bootstrapping, implementation patterns, validation commands, and delivery checklists.

Quick Start

Always choose one of these starts:

# HTTP MCP server scaffold
polymcp init my-server --type http-server --with-examples

# Stdio MCP server scaffold
polymcp init my-stdio --type stdio-server --with-examples

# Agent scaffold (for orchestration projects)
polymcp init my-agent --type agent --with-examples

Then run from the created project:

python server.py
polymcp test server http://localhost:8000/mcp
polymcp test tool http://localhost:8000/mcp greet --params '{"name":"World"}'

Build Workflow

1. Define target.

• Confirm transport (http or stdio).
• Confirm tools to expose and expected request/response shape.
• Confirm auth and runtime constraints.

2. Implement server.

• Keep each tool small and single-purpose.
• Add typed parameters and useful docstrings.
• Keep startup/boot path deterministic.

3. Validate behavior.

• Verify discovery via list_tools.
• Verify one happy-path invoke and one failure-path invoke.
• Capture commands and outputs for reproducibility.

4. Register and orchestrate.

• Add server into registry if required by agent workflow.
• Validate agent-level consumption.

5. Deliver with runbook.

• Include exact setup, run, and test commands.
• Include rollback or known constraints when relevant.

Tool Pattern (Python)

Use explicit, typed functions:

from polymcp import expose_tools_http

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

app = expose_tools_http(
    tools=[add],
    title="Math Server",
    description="MCP tools over HTTP",
)

Validation Baseline

polymcp test server http://localhost:8000/mcp
polymcp test tool http://localhost:8000/mcp add --params '{"a":2,"b":3}'
polymcp server add http://localhost:8000/mcp --name local
polymcp server list --json

For stdio servers:

polymcp test stdio python server.py

Build Rules

• Keep tools small and single-purpose.
• Avoid silent failures; return structured errors.
• Avoid adding dependencies unless required by the use case.
• Prefer reproducible commands over manual steps.
• Prefer reversible changes during active troubleshooting.

Common Mistakes

• Wrong URL path (missing /mcp).
• Tool signature changed without updating expected params.
• Non-serializable tool return values.
• Stdio command/args mismatch at registration time.