design-mcp-server

When to Use

• User says "I want to build a ___ MCP server"
• User has an API, database, or system they want to expose to LLMs
• User wants to plan tools before scaffolding
• Existing server needs a new capability area (design the addition, not just a single tool)

Do NOT use for single-tool additions — use add-tool directly.

Inputs

Gather before designing. Ask the user if not obvious from context:

1. Domain — what system, API, or capability is this server wrapping?
2. Data sources — APIs, databases, file systems, external services?
3. Target users — what will the LLM (and its human) be trying to accomplish?
4. Scope constraints — read-only? write access? admin operations? what's off-limits?

If the domain has a public API, read its docs before designing. Don't design from vibes.

Steps

1. Research External Dependencies

Before designing, verify the APIs and services the server will wrap.

If the Agent tool is available, spawn background agents to research in parallel while you proceed with domain mapping:

• Fetch API docs, confirm endpoint availability, auth methods, rate limits
• Check for official SDKs or client libraries (npm packages)
• Note any API quirks, pagination patterns, or data format considerations

If the Agent tool is not available, do this research inline — fetch docs, read SDK readmes, confirm assumptions before committing them to the design.

2. Map the Domain

List the concrete operations the underlying system supports. Group by domain noun.

Example for a project management API:

Noun	Operations
Project	list, get, create, archive
Task	list (by project), get, create, update status, assign, comment
User	list, get current

This is the raw material. Not everything becomes a tool.

3. Classify into MCP Primitives

Primitive	Use when	Examples
Tool	Needs parameters beyond a simple ID, has side effects, or requires LLM decisions about inputs	Search, create, update, analyze, transform
Resource	Addressable by stable URI, read-only, useful as injectable context	Config, schemas, status, entity-by-ID lookups
Prompt	Reusable message template that structures how the LLM approaches a task	Analysis framework, report template, review checklist
Neither	Internal detail, admin-only, not useful to an LLM	Token refresh, webhook setup, migrations