---
name: mcp-server-builder
description: "Plans, builds, and tests an MCP server from the tools it should expose through schemas, auth, error handling, and an evaluation set that proves agents can use it. Use when a service or dataset needs to be exposed to AI agents through a new MCP server with well-designed tools, schemas, auth, and tests. Do not use for using an existing MCP server or building a non-MCP plugin system. Related topics: AI, coding."
---

# MCP Server Builder

Plans, builds, and tests an MCP server from the tools it should expose through schemas, auth, error handling, and an evaluation set that proves agents can use it.

## When to use

Use this skill when a service or dataset needs to be exposed to AI agents through a new MCP server with well-designed tools, schemas, auth, and tests. Do not use it for using an existing MCP server or building a non-MCP plugin system.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Group the key operations into a small set of task-shaped tools instead of mirroring every API endpoint.
3. Write each tool name, a description saying when to use it, and a typed input schema with described fields.
4. Shape tool results to be compact, paginated, and readable, and write errors that say what failed and what to try next.
5. Add authentication, secret handling, and confirmation inputs for destructive tools, honouring the read-only setting.
6. Produce the server code, ten multi-call evaluation questions with expected answers, and a test plan using an inspector.

## Inputs

- **Service or data to expose** (longer free text)
- **Language and SDK** (choose one: TypeScript, Python, Go, Other)
- **Transport** (choose one: stdio, Streamable HTTP)
- **Authentication** (choose one: None, API key, OAuth, Per-user token)
- **Read-only** (choose one: Yes, No)
- **Key operations** (longer free text)

## Output

The server code, a tool table with name, purpose, and schema, ten evaluation questions with expected answers, and a short test plan.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### MCP Server Builder

Design and implement an MCP server for the service below.

- Service or data to expose: {{Service or data to expose}}
- Language and SDK: {{Language and SDK}}
- Transport: {{Transport}}
- Authentication: {{Authentication}}
- Read-only: {{Read-only}}
- Key operations: {{Key operations}}

Begin by choosing tools around tasks an agent wants to finish, not around raw API endpoints; combine calls that always go together and keep the total number of tools small. Give every tool a clear name, a description that says when to use it and when not to, and an input schema with typed, described fields and sensible defaults. Return results that are compact and useful to a model: trimmed fields, human-readable identifiers, and pagination with a clear next-step hint. Make errors actionable, telling the agent what was wrong and what to try next. Mark destructive tools clearly and require confirmation inputs where harm is possible. Keep secrets in environment variables and never return them in output.

Write the server code, then ten realistic evaluation questions with expected answers that need several tool calls, and a short test plan using an inspector to check each tool.

## Pitfalls

- Exposing one tool per endpoint, which gives the agent forty similar choices and confuses selection.
- Returning whole raw API responses that flood the context window with fields the task never needs.
- Writing errors like Bad Request, which leave the agent no way to recover.