Purpose

Guide the full development lifecycle of an MCP server — from understanding the target API, through designing the tool/resource/prompt surface, to implementation, testing, and deployment. This is the hub skill for MCP server projects that span multiple phases.

When to use this skill

• Building a new MCP server that wraps an external API or service
• Planning which tools, resources, and prompts an MCP server should expose
• Iterating on an existing MCP server (adding tools, improving schemas, fixing patterns)
• Need a structured development workflow rather than ad hoc implementation

Do not use this skill when

• Scaffolding a first-ever MCP server → use

  get-started

• The task is narrowly about one tool's schema design → use

  mcp-tool-design

• The task is only about testing → use

  mcp-testing-evals

• Following a specific SDK's patterns → use

  mcp-typescript-sdk

  or

  mcp-python-fastmcp

Operating procedure

Phase 1 — Research and plan

1. Study the target API. Read its documentation. Identify key endpoints, auth model, data shapes, rate limits, and pagination patterns.
2. Map endpoints to MCP primitives:
   • Tools — for actions the LLM should invoke (queries, mutations, computations)
   • Resources — for read-only context data the host can present (schemas, configs, documentation)
   • Prompts — for reusable interaction templates (e.g., "analyze this data using the available tools")
3. Decide coverage strategy. Prioritize comprehensive API coverage over bespoke workflow tools. Comprehensive coverage lets agents compose operations flexibly.
4. Choose stack. TypeScript (recommended for broadest compatibility) or Python (FastMCP for rapid development). See

   mcp-typescript-sdk

   or

   mcp-python-fastmcp

   .

Phase 2 — Implement core infrastructure

1. API client wrapper — centralized auth, error handling, retry logic
2. Response formatting — consistent JSON or Markdown output across tools
3. Pagination helper — many APIs and MCP

   */list

   methods use cursor-based pagination
4. Error mapping — translate API errors to MCP error format:
   • Protocol errors: standard JSON-RPC error codes (-32600 to -32603)
   • Tool execution errors:

     { isError: true, content: [{ type: "text", text: "..." }] }

Phase 3 — Implement primitives

For each tool:

1. Define

   inputSchema

   using Zod (TS) or Pydantic/type hints (Python)
2. Write a clear

   description

   — this is what the LLM reads to decide when to use the tool
3. Set

   annotations

   :

   readOnlyHint

   ,

   destructiveHint

   ,

   idempotentHint

   ,

   openWorldHint

4. Implement the handler with async I/O, proper error handling, and pagination support
5. Optionally define

   outputSchema

   for structured responses

For each resource:

1. Choose a URI scheme (e.g.,

   file://

   ,

   https://

   , or custom)
2. Implement

   resources/list

   and

   resources/read

3. Support

   resources/subscribe

   if the data changes over time

For each prompt:

1. Define the prompt name, description, and arguments
2. Return structured

   messages

   array with

   role

   and

   content

Phase 4 — Declare capabilities

In the

initialize

response, declare what the server supports:

{
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": true, "listChanged": true },
    "prompts": { "listChanged": true },
    "logging": {}
  }
}

Only declare capabilities you actually implement.

Phase 5 — Test and validate

1. Build:

   npm run build

   (TS) or

   python -m py_compile

   (Python)
2. Inspector:

   npx @modelcontextprotocol/inspector

   — verify all tools list, call correctly, return expected schemas
3. Host test: Connect to a real host (Claude Desktop, VS Code, Codex) and verify end-to-end
4. Edge cases: Test with invalid inputs, missing auth, rate-limited APIs, empty results

Phase 6 — Ship

1. Choose transport (stdio for local, Streamable HTTP for remote)
2. Add auth if remote (see

   mcp-auth-transports

   )
3. Write README with installation and configuration instructions
4. Publish to npm/PyPI or register in an MCP registry

Decision rules

• Tool naming: Use

  <domain>_<action>

  prefix pattern (e.g.,

  github_create_issue

  ,

  github_list_repos

  ) for discoverability
• Tool count: Start with the most common 10-15 operations. Expand based on usage, not speculation.
• Resource vs Tool: If the LLM needs to take action → tool. If the host needs context → resource.
• Error messages: Include what went wrong AND what to try next. "API returned 403: check that the API key has write permissions for this repository."
• DRY: Extract shared API client, pagination, and formatting into utility modules

Output requirements

1. Working MCP server with declared capabilities
2. All tools have

   inputSchema

   ,

   description

   , and

   annotations

3. Passes MCP Inspector verification for all primitives
4. README with host configuration examples

Related skills

• mcp-tool-design

  — deep dive on individual tool design

• mcp-resources-prompts

  — resource and prompt implementation patterns

• mcp-testing-evals

  — testing strategy and evaluation creation

• mcp-builder

  — reference implementation guide from Anthropic

Failure handling

• If the target API has no documentation, use the API's OpenAPI/Swagger spec if available; otherwise explore endpoints manually and document as you go
• If a tool is too complex for a single call, split into a read step and a write step rather than one tool that does both
• If tool count exceeds 30, consider splitting into multiple focused MCP servers rather than one monolith