# mcp-server-architect

A subagent that designs and writes MCP servers: tools, transports, sessions, security. Useful when you need a working server, not a sketch.

- subagent · `type=agent` · Claude Code · 1649 installs
- Author: davila7
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/mcp-dev-team/mcp-server-architect.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/agents/mcp-server-architect

## What it does

The subagent walks an MCP server from design to deployment. It studies the domain first, then proposes tool interfaces with JSON Schema validation, annotations (read-only, destructive, idempotent, open-world) and value hints through `completion/complete`. Transport work follows: JSON-RPC 2.0 over stdio and Streamable HTTP, with an SSE fallback for older clients.

Its standards are spelled out. Code comes in TypeScript with `@modelcontextprotocol/sdk` (1.10.0 or newer) or in Python with type hints. Sessions get non-deterministic IDs tied to a user identity, and every Streamable HTTP request has its `Origin` header checked. Caching, connection pooling and multi-region deployment are part of the brief. Logs go to stderr — send them to stdout and the protocol breaks.

The subagent holds `Read`, `Write`, `Edit` and `Bash`, so it edits files and runs commands on its own. It targets the 2025-06-18 MCP specification; on an older protocol version you will have to discard some of its advice by hand. Without a grasp of JSON-RPC and the session lifecycle, the output is hard to debug.

## Install

### Claude Code (native platform)

1. **claude-code-templates**
```bash
npx claude-code-templates@latest --agent mcp-dev-team/mcp-server-architect
```

2. **Manually: put the files in place**
- File: `.claude/agents/mcp-server-architect.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/mcp-server-architect.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/mcp-server-architect.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/davila7/claude-code-templates/tree/HEAD/cli-tool/components/agents/mcp-dev-team/mcp-server-architect.md

## When to use it
- lay out a server's tool set with input validation
- run stdio and Streamable HTTP transports side by side
- wire up argument suggestions via `completion/complete`
- harden sessions and `Origin` checks without leaking IDs
- keep protocol output and logs on separate streams

## Example prompts
- Design an MCP server for our internal knowledge base: tools, resources, prompts
- Add `completion/complete` support for the arguments of the search tool
- Check that the server returns proper errors and keeps logs out of stdout

## Similar
- [mcp-copilot-studio-server-generator](https://affpapa.org/en/nevibecode/skills/mcp-copilot-studio-server-generator.md) — skill · 8700 installs
- [basebalance.cloud — x402 RPC & MCP gateway](https://affpapa.org/en/nevibecode/mcp/basebalancecloud-x402-rpc-mcp-gateway.md) — MCP server · ★ 7548
- [frontend-developer](https://affpapa.org/en/nevibecode/agents/voltagent-community-frontend-developer.md) — subagent · 40905 installs
- [dx-optimizer](https://affpapa.org/en/nevibecode/agents/dx-optimizer.md) — subagent · 1198 installs
- [mlops-engineer](https://affpapa.org/en/nevibecode/agents/voltagent-community-mlops-engineer.md) — subagent · 1009 installs
- [postgres-pro](https://affpapa.org/en/nevibecode/agents/postgres-pro.md) — subagent · 897 installs
- [agent-installer](https://affpapa.org/en/nevibecode/agents/agent-installer.md) — subagent · 363 installs
- [embedded-systems](https://affpapa.org/en/nevibecode/agents/embedded-systems.md) — subagent · 279 installs

From the same set: [davila7/claude-code-templates](https://affpapa.org/en/nevibecode/by/davila7/claude-code-templates.md) — 361 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md