MCP Architect

What this skill does

• Designs an MCP server from a description: primitives (tools/resources/prompts), a least-privilege surface
• Writes **correct tool schemas** (JSON Schema 2020-12), descriptions, output schemas and honest annotations
• Scaffolds runnable code for **Python (FastMCP)** or **TypeScript (SDK)** — with clean stdout
• Picks the **transport** (stdio local / Streamable HTTP remote) and plans **OAuth 2.1** for remote servers
• Guides **testing** (MCP Inspector) and the common failures (the stdout "disconnected" classic)
• Generates a valid **`server.json`** and walks publishing to the official MCP Registry
• Two defensive Node scripts: **server scaffolder** + **server.json validator** (zero dependencies)

Description

MCP Architect is a skill for building Model Context Protocol (MCP) servers — it turns a description ("let Claude query our Postgres", "wrap our API as tools") into a well-designed, secure, **runnable** MCP server. The core rule: **an MCP server is only as good as its tool schemas** — about 80% of quality. So it designs the interface first, then the code: the right **primitives** (tools, resources, prompts — only what the use-case needs), clear names, **model-readable descriptions**, constrained input schemas (JSON Schema 2020-12, object root — never a free-form `url`/`path`/`cmd` on a powerful action), structured outputs, and honest **annotations** (readOnly/destructive/idempotent/openWorld — informational hints, not a security boundary). It knows the **2026-07-28 spec** reality: a stateless core, **stdout is the JSON-RPC channel** (a single `print()` breaks the server → "disconnected", which is why all logs go to stderr), **Streamable HTTP** over the deprecated SSE transport, and that Roots/Sampling/Logging are deprecated. It picks the **transport** to match complexity: stdio for local (no auth), Streamable HTTP for remote — and then **OAuth 2.1 done right** (resource server, RFC 9728 metadata, RFC 8707 resource indicators, PKCE S256, `aud` validation, validate Origin, bind 127.0.0.1 locally). It scaffolds runnable code for **Python (FastMCP 2.x)** or **TypeScript (@modelcontextprotocol/sdk)** — with two bundled, zero-dependency Node scripts: a **server scaffolder** (correct starter with clean stdout, schema, annotations) and a **server.json validator** for the official **MCP Registry**. Testing is via the **MCP Inspector**; publishing via `server.json` + Registry. It is **verify-live** (MCP changes monthly → current spec/SDK with version), invents no API details, and is **secure by design** (least privilege, human gates) — for the deep security audit of a finished server it points to **Agent Warden**.

Examples

Tested with Claude Code

import logging, sys; logging.basicConfig(stream=sys.stderr)   # logs to stderr — stdout is JSON-RPC
from fastmcp import FastMCP
mcp = FastMCP("pg-reader")

REPORTS = {"active_users": "select id,email from users where active"}  # allow-list, parameterized

@mcp.tool(annotations={"readOnlyHint": True, "openWorldHint": True})
def run_report(report: str, limit: int = 100) -> str:
    """Run a pre-approved read-only report."""
    if report not in REPORTS: return f"Error: unknown report. Try: {', '.join(REPORTS)}"
    return "(stub) rows…"

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

What it does not do

• **Not a hosting/runtime** — it designs and scaffolds; running/deploying is on you
• **Not a security auditor** — for the deep audit of a finished server (prompt injection, tool poisoning, excessive agency) → Agent Warden
• **Invents no spec/API details** — MCP changes monthly, verify-live with a version
• **Not classic backend/API engineering** beyond the MCP layer, and not client/agent building

Compatibility & tech

Tested (internal)

3 scenarios

Recommended runtime

Claude Opus or Sonnet; with web access for verify-live against the current MCP spec/SDK APIs. The scripts need Node (no extra packages); without Node the skill produces code/metadata by hand from the references.

Modes

Design (shape the interface) · Scaffold / build (generate code) · Tool design (schema, annotations, errors) · Auth & transport · Publishing (server.json / Registry)

Inputs

description of the desired server · API / database / tool spec · existing MCP server code (to improve) · language/SDK preference (Python/TypeScript)

Output format

MCP server design (primitives + tool table) + runnable code (Python/TypeScript) + auth/transport plan + test & publishing steps

Subcategory

MCP servers & AI tool integration

License

Proprietär

Security profile

What you get

• mcp-architect-1.0.0/11 files
  • .claude-plugin/marketplace.json
  • plugins/mcp-architect/skills/mcp-architect/11 files

    • SKILL.md
    • manifest.json
    • references/7 files

      • mcp-architect-auth-transport.md
      • mcp-architect-publish.md
      • mcp-architect-python-fastmcp.md
      • mcp-architect-spec.md
      • mcp-architect-test-debug.md
      • mcp-architect-tool-design.md
      • mcp-architect-typescript-sdk.md
    • scripts/2 files

      • scaffold-mcp.mjs
      • validate-server-json.mjs
  • .agents/skills/mcp-architect/→ universal — same content (Codex, Cursor, Copilot, Gemini, Windsurf, Cline)
  • LICENSE.txt

Installation

Also works as a chat prompt

Note

MCP evolves monthly — with web access MCP Architect verifies the current spec (modelcontextprotocol.io) and the SDK APIs live and cites the version (this skill targets the 2026-07-28 spec). It designs and scaffolds; running/deploying the server is on you. For a deep security audit of a finished server → Agent Warden. The bundled scripts need Node (no extra packages).

Changelog

• v1.0.021.08.2026Initial release: turns a description into a clean, secure, runnable MCP (Model Context Protocol) server. Designs the primitives (tools/resources/prompts), writes correct tool schemas + annotations, picks the transport (stdio vs Streamable HTTP), scaffolds Python (FastMCP) or TypeScript (@modelcontextprotocol/sdk) code with clean stdout, plans OAuth 2.1 for remote servers, and guides testing (MCP Inspector) and publishing (server.json / official Registry). Targets the MCP 2026-07-28 spec (stateless core, SSE deprecated). Two Node scripts (server scaffolder, server.json linter), 7 references. Verify-live; deep security audit → Agent Warden.

Frequently asked questions