Production-Quality MCP Server

What you're building

A stdio MCP server that a stranger could clone, configure with their own credentials, and connect to Claude Desktop or Claude Code by following your README alone. At least four task-level tools (not endpoint mirrors), one resource, one prompt. Every tool description states purpose, arguments, output shape, and when not to use it. Large results paginate with explicit more-available signals; every error path returns actionable text; one destructive tool hides behind two-phase confirm; and a run_python tool executes agent code in a locked-down Docker container. Then you prove all of it with tests. Pick an API you genuinely use — a real one forces the real design decisions (which five tasks matter, what a shaped summary looks like, where pagination bites); GitHub or Jira work if work APIs are off-limits, but avoid toys — "production-quality weather wrapper" is an oxymoron on a portfolio.

Suggested structure

# server.py
import os

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-api-server")

API_KEY = os.environ.get("MYAPI_KEY")
if not API_KEY:
    raise SystemExit("MYAPI_KEY not set -- see README configuration.")


@mcp.tool()
def search_things(query: str, status: str = "open",
                  page: int = 1, page_size: int = 20) -> str:
    """One-paragraph purpose. Output shape. When NOT to use this.
    Pagination contract: page_size max 50; response states if more exist."""
    # TODO: call the real API; shape results into lines;
    # append MORE AVAILABLE trailer when truncated;
    # branch on 401/404/429 -> instructive error strings
    ...


@mcp.tool()
def dangerous_thing(item_id: str, confirm: bool = False) -> str:
    """DESTRUCTIVE. confirm=False returns a preview only."""
    ...


@mcp.tool()
def run_python(code: str, timeout_s: int = 30) -> str:
    """Sandboxed execution: docker run --rm --network none
    --memory 512m, timeout, non-root, read-only. See Lesson 5."""
    ...


@mcp.resource("myapi://reference/statuses")
def statuses() -> str: ...


@mcp.prompt()
def investigate(item_id: str) -> str: ...


if __name__ == "__main__":
    mcp.run()   # stdio

# tests/test_tools.py        -- unit: tool logic with the API mocked
# tests/test_protocol.py     -- integration: stdio_client + ClientSession,
#                               initialize, list_tools, call each tool,
#                               assert on error strings for bad IDs
# tests/test_sandbox.py      -- prove "import socket; ...connect..." FAILS,
#                               and that a 60s sleep is killed by timeout

Ship it to your portfolio

• README that demos in 60 seconds: open with a short GIF or clip of a real client (Claude Desktop or Claude Code) driving your tools — hiring managers look at GitHub before the résumé, and a repo that shows itself working gets read; one that starts with install steps gets skimmed.
• Show the passing test suite: paste the output of all three test layers (unit, protocol integration, sandbox) into the README. A green test run for an MCP server is exactly the evidence Gate G3 asks for, and it separates an evaluated project from a demo.
• An honest "Limitations" section: what the server doesn't handle (rate-limit backoff strategy, pagination edge cases, which API surface you deliberately skipped) and what you'd do next. Stated limits read as engineering judgment, not weakness.
• Say how you sandboxed and authenticated it: one short paragraph on the run_python isolation (which container flags, which test proves them) and one on the credential story (env vars, scope, what the stretch-goal HTTP+bearer setup would change). Sandboxed execution is a named skill in agent-engineer postings — make it findable.