MCP Server Builder Playbook
Build, test, and deploy a production MCP server — scaffold, IDE integration, and tool description polish.
Why this playbook
MCP (Model Context Protocol) lets any LLM use your API as a set of callable tools. But a good MCP server isn't just 'expose every endpoint' — it needs well-described tools, proper input validation, and IDE integration that actually works.
This playbook goes from zero to a deployed MCP server in three steps: scaffold the server with proper tool definitions, configure it for your IDE (Claude Code or Cursor), and polish the tool descriptions so LLMs actually choose the right tool.
The third step — description tightening — is where most MCP servers fail. A vague tool description means the LLM guesses wrong about which tool to use. This playbook fixes that.
Prerequisites
- An API you want to wrap (REST, GraphQL, or SDK)
- Node.js 20+ or Python 3.11+
- Claude Code or Cursor IDE installed
- Basic understanding of the MCP protocol (or read /stack/mcp first)
Input requirements
| Input | Type | Required | Description |
|---|---|---|---|
| API documentation or OpenAPI spec | URL or file | Yes | The API you want to wrap. An OpenAPI/Swagger spec is ideal. Fallback: docs URL or raw endpoint list. |
| Target IDE | string | Yes | 'claude-code' or 'cursor'. Determines the config file format and setup instructions. |
| Target language | string | No | TypeScript (default) or Python. Determines which MCP SDK the scaffold uses. |
Step-by-step workflow
Scaffold the MCP server with tool definitions
Open promptThis prompt reads your API docs or spec and generates a complete MCP server: tool definitions with typed inputs, error handling, authentication wiring, and a local test harness.
The scaffold follows MCP best practices: one tool per logical action (not per HTTP endpoint), grouped by capability, with clear input schemas that include descriptions and examples.
Configure IDE integration
Open promptThis prompt generates the IDE config needed to connect your MCP server. For Claude Code: .claude/settings.json entries. For Cursor: .cursor/mcp.json entries. It also generates a test script that verifies the connection works.
The prompt handles the common gotchas: correct working directory paths, environment variable passthrough, and process management (stdio vs HTTP transport).
Polish tool descriptions for LLM accuracy
Open promptThe difference between a usable MCP server and a great one is the tool descriptions. This prompt reviews every tool in your server and rewrites descriptions to be unambiguous, specific, and actionable.
It applies three rules: (1) lead with what the tool does, not what it is, (2) include the most common use case in the description, (3) specify what the tool does NOT do to prevent misuse. Before/after comparisons show the improvement.
Expected outputs
MCP server package
Complete MCP server with tool definitions, auth wiring, error handling, and local test harness.
Produced by step 1IDE configuration
Ready-to-use config for Claude Code or Cursor, with test script to verify the connection.
Produced by step 2Polished tool descriptions
Rewritten tool descriptions optimized for LLM tool selection accuracy, with before/after diffs.
Produced by step 3Tool requirements
- Claude Code or Cursor
- Node.js 20+ or Python 3.11+
- An API you want to wrap as MCP tools
Troubleshooting
MCP server starts but LLM never calls the tools
Cursor shows 'MCP server disconnected' after a few minutes
Tool inputs don't match the API's expected format
Share as social post
MCP Server Builder Playbook 3 steps, 45-60 minutes. Build, test, and deploy a production MCP server — scaffold, IDE integration, and tool description polish. https://agntdot.com/playbooks/mcp-server-builder-playbook
217 / 280 chars