Server-per-capability vs monolith
What you'll learn
Build one MCP server per integration (git, Jira, Postgres). Don't bundle them into one giant company server.
- Server-per-capability is the default. Monolith is the antipattern.
- Tool list bloat reduces model selection accuracy at ~10+ tools.
- Independent versioning, smaller blast radius, finer-grained auth.
MCP server design strongly favours **server-per-capability** over **monolithic 'company server' designs**. A capability is a coherent integration target — git, filesystem, Jira, Postgres. One MCP server per capability means tight focus on the schemas and descriptions of *that* integration, independent versioning, smaller blast radius for failures, and the ability to compose servers in the client (Claude Code, etc.) without inheriting unrelated dependencies.
The monolith antipattern: a single 'company-wide MCP server' that bundles git + Jira + Postgres + S3 + every other internal integration into one process. Symptoms: tool list bloats (the model sees 50+ tools at once and selection accuracy drops), deploys become risky (any change touches the shared surface), permissions get coarse-grained (you either auth into the whole monolith or none of it), and one buggy integration takes the whole server down.
The right defaults: scope each server to one integration; let the client compose. Most MCP clients (including Claude Code) connect to multiple servers concurrently — there's no operational benefit to bundling. The two reference servers worth studying as exemplars: the Filesystem server and the Git server in `modelcontextprotocol/servers` — small, focused, single-capability.
When a monolith *is* tempting (shared auth, shared rate-limits, shared logging), the better answer is usually a thin wrapper or sidecar that handles the cross-cutting concern outside the server, keeping the per-capability servers small. The exam frames this exactly: 'should we build one company server or many smaller servers?' — the right answer is many small ones.
Key points
- Server-per-capability is the default. Monolith is the antipattern.
- Tool list bloat reduces model selection accuracy at ~10+ tools.
- Independent versioning, smaller blast radius, finer-grained auth.
- Clients compose multiple servers concurrently — there's no need to bundle.
Examples
git-mcp · jira-mcp · postgres-mcp · s3-mcp. Each ~10 well-described tools. Each independently auth'd, deployed, versioned. Claude Code connects to all four; the model sees a focused tool list per capability.
One server, 60 tools across 8 integrations. Tool descriptions inevitably overlap (search_jira_tickets vs search_zendesk_tickets vs search_internal_docs). Selection accuracy degrades. Auth is all-or-nothing. Deploy is high-risk.
Pitfalls
- Reaching for a monolith because 'one server is easier to deploy.' True for now; expensive forever.
- Underestimating tool-list bloat. The model is reading every description on every call; 50 tools is a lot of context.
- Bundling because 'shared auth.' Sidecar / proxy patterns handle shared concerns without forcing the bundle.
Source notes: 00-academy-basics/notes/05-mcp-intro.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.