MCP Server Builder

Build production-ready MCP servers that expose tools and resources to Claude Code and other MCP clients.

Prerequisites

• Node.js 18+ or Python 3.10+ installed
• Understanding of the domain the server will serve
• Familiarity with JSON-RPC and REST API patterns

Workflow

Step 1: Define Server Purpose

Gather the following from the user:

1. Server name - kebab-case identifier (e.g., weather-api, jira-connector)
2. Language - TypeScript (recommended) or Python
3. Tools - list of actions the server exposes (name, description, parameters)
4. Resources - list of data the server provides (URI patterns, MIME types)
5. Authentication - none, API key, OAuth 2.0, or custom
6. Transport - stdio (default) or SSE (server-sent events)

Step 2: Scaffold the Project

Create the project structure:

<server-name>/
  src/
    index.ts          # Entry point and server setup
    tools/            # Tool handler implementations
    resources/        # Resource provider implementations
    auth/             # Authentication middleware
  package.json        # Dependencies and scripts
  tsconfig.json       # TypeScript configuration
  .env.example        # Environment variable template
  README.md           # Setup and usage documentation

For Python projects, use:

<server-name>/
  src/
    __init__.py
    server.py         # Entry point and server setup
    tools/            # Tool handlers
    resources/        # Resource providers
  pyproject.toml      # Dependencies
  .env.example
  README.md

Step 3: Implement the Server Core

1. Initialize the MCP server with name and version
2. Register tool handlers with input schemas (JSON Schema)
3. Register resource providers with URI templates
4. Configure transport layer (stdio or SSE)
5. Add error handling and logging

Step 4: Define Tool Schemas

For each tool, define:

1. name - unique identifier in snake_case
2. description - clear explanation of what the tool does and when to use it
3. inputSchema - JSON Schema for parameters with required fields
4. handler - async function that executes the tool logic

Step 5: Define Resource Providers

For each resource, define:

1. URI pattern - template like myserver://items/{id}
2. name - human-readable name
3. description - what data this resource provides
4. mimeType - content type (e.g., application/json, text/plain)
5. handler - async function that returns the resource content

Step 6: Add Authentication

Based on the chosen auth method:

• API Key: Read from environment variable, attach to outgoing requests
• OAuth 2.0: Implement token refresh flow, store tokens securely
• Custom: Implement the specific auth protocol required

Step 7: Test Locally

1. Build the project: npm run build or equivalent
2. Run with stdio transport for quick testing
3. Configure in Claude Code's settings.json under mcpServers
4. Verify each tool and resource responds correctly
5. Test error cases and edge conditions

Output Format

The skill produces:

• Complete project directory with all source files
• package.json or pyproject.toml with correct dependencies
• Tool and resource implementations with proper schemas
• Authentication setup if required
• README with installation and configuration instructions

Examples

Example 1: Database Query Server

User: "Build an MCP server that queries our PostgreSQL database"

Action: Scaffold a TypeScript MCP server with tools for query_table, list_tables, describe_table, and resources for db://tables/{name}/schema.

Example 2: REST API Wrapper

User: "Create an MCP server for the GitHub API"

Action: Scaffold a server with tools for create_issue, list_repos, search_code, resources for github://repos/{owner}/{repo}, and OAuth 2.0 authentication.

Example 3: File Processing Server

User: "Make an MCP server that converts CSV files to JSON"

Action: Scaffold a server with a convert_csv tool that accepts file paths and conversion options, returning structured JSON output.

Best Practices

1. Write detailed tool descriptions - the LLM uses these to decide when to call your tool
2. Use strict input schemas - validate all parameters with JSON Schema
3. Return structured errors - use MCP error codes, not raw exceptions
4. Keep tools focused - one tool per action, not one mega-tool
5. Log all operations - use stderr for debug logs (stdout is the transport)
6. Handle timeouts - set reasonable timeouts for external API calls
7. Version your server - bump version when tool schemas change
8. Document environment variables - list all required config in .env.example

Error Handling