---

name: switchblade description: > Build MCP servers from scratch with protocol-compliant tool, resource, and prompt definitions. USE WHEN: User needs to create an MCP server, define tools for AI agents, implement stdio or SSE transports, test MCP integrations, or deploy MCP servers. DON'T USE WHEN: User needs to use existing MCP tools (use the specific integration skill). Use Phantom for agent architecture. Use Hivemind for multi-agent orchestration. OUTPUTS: MCP server implementations, tool/resource/prompt definitions, transport configurations, test suites, deployment configs, protocol-compliant schemas. version: 1.0.0 author: SpookyJuice tags: [mcp, model-context-protocol, tool-generation, server-builder, protocol, integration] price: 14 author_url: "https://www.shopclawmart.com" support: "brian@gorzelic.net" license: proprietary osps_version: "0.1"

Switchblade

Version: 1.0.0 Price: $14 Type: Skill

Description

The Model Context Protocol (MCP) is becoming the standard interface between AI agents and external tools, but building a compliant MCP server from the spec alone is an exercise in frustration. The protocol has nuances around transport negotiation, capability advertisement, error codes, and lifecycle management that aren't obvious from the JSON-RPC surface. Switchblade gives you the complete playbook for building MCP servers that work correctly with Claude, OpenClaw, and any MCP-compliant client.

This skill covers both transport layers (stdio for local integrations, SSE for remote), the three primitive types (tools, resources, prompts), input validation with JSON Schema, proper error handling and error codes, server lifecycle management, and testing strategies that verify protocol compliance -- not just happy-path functionality. You get patterns for wrapping existing APIs, CLIs, and databases as MCP tools, plus deployment configurations for running servers in production.

Whether you're building a one-tool server to expose a single API endpoint or a full integration platform with dozens of tools and dynamic resources, Switchblade gives you the architecture to do it right the first time.

Prerequisites

• Node.js 18+ or Python 3.11+ runtime
• @modelcontextprotocol/sdk (TypeScript) or mcp (Python) SDK
• An MCP-compatible client for testing (Claude Desktop, Claude Code, or OpenClaw)
• Basic understanding of JSON-RPC 2.0
• For SSE transport: HTTP server framework (Express, Fastify, or Flask)

Setup

1. Copy SKILL.md into your OpenClaw skills directory
2. Install the MCP SDK for your language:

   # TypeScript
   npm install @modelcontextprotocol/sdk zod
   # Python
   pip install mcp pydantic
   

3. Reload OpenClaw

Commands

• "Build an MCP server for [API/service/database]"
• "Define MCP tools for [set of operations]"
• "Add resources to my MCP server for [data type]"
• "Implement SSE transport for remote MCP access"
• "Write tests for my MCP server"
• "Deploy my MCP server to [platform]"
• "Wrap [CLI tool] as an MCP server"
• "Add prompt templates to my MCP server"
• "Debug MCP protocol compliance issues"

Workflow

Building an MCP Server from Scratch

1. Scope definition -- decide what your server exposes: tools (actions the agent can take), resources (data the agent can read), and prompts (reusable prompt templates). Start with tools only -- they're the most common and most useful. Add resources when agents need to browse or read structured data. Add prompts when you have domain-specific prompt patterns worth reusing.
2. Tool design -- each tool needs: a unique name (kebab-case), a human-readable description (this is what the LLM reads to decide whether to use the tool), an input schema (JSON Schema defining parameters with types, descriptions, and constraints), and an output format. The description is critical -- vague descriptions produce wrong tool selections. Be specific about what the tool does, what inputs it expects, and what outputs it returns.
3. Input validation -- validate all inputs against the JSON Schema before executing. Use Zod (TypeScript) or Pydantic (Python) for runtime validation. Return structured error responses (not exceptions) when validation fails. Include: which parameter failed, why it failed, and what was expected. The agent uses this feedback to retry with corrected inputs.
4. Implementation -- implement each tool handler: receive validated inputs, call your underlying API/service/database, transform the response into the format your schema promises, and return it. Handle timeouts, rate limits, and service errors gracefully. Every tool handler should be independently testable.
5. Transport selection -- stdio for local-only servers (simplest, best for CLIs and desktop integrations), SSE for remote servers (agents connect over HTTP, supports multiple concurrent clients). Stdio servers are started as child processes by the client. SSE servers run as long-lived HTTP services. Choose based on your deployment model.
6. Server initialization -- implement the server lifecycle: capability advertisement (what tools/resources/prompts you offer), initialization handshake, and graceful shutdown. The server must respond to initialize with its capabilities before any tool calls are accepted.
7. Error handling -- MCP defines specific error codes. Use them correctly: InvalidParams (-32602) for bad inputs, MethodNotFound (-32601) for unknown tools, InternalError (-32603) for server-side failures. Include human-readable error messages that help the agent (and the developer) understand what went wrong.

Wrapping an Existing API

1. API analysis -- document the API endpoints you want to expose: HTTP method, URL pattern, required/optional parameters, authentication, rate limits, and response format. Group related endpoints into logical tools (e.g., a CRUD API might become four tools: create, read, update, delete, or one tool with an "action" parameter).
2. Tool mapping -- map each API operation to an MCP tool. Naming convention: service-action (e.g., github-create-issue, slack-send-message). Each tool's input schema mirrors the API's required parameters, with descriptions explaining what each parameter does. Don't expose every API parameter -- focus on the ones agents actually need.
3. Authentication -- handle API credentials server-side. The MCP server reads API keys from environment variables at startup. Never expose credentials in tool schemas or responses. If the API uses OAuth, implement token refresh in the server and handle token expiry gracefully.
4. Response transformation -- raw API responses are often too large or too complex for an agent's context window. Transform responses: extract the relevant fields, flatten nested structures, truncate long text fields, and format the result as a clean JSON object or markdown. Include pagination metadata if the API paginates.
5. Rate limit management -- implement rate limiting in your server, not just relying on the API's limits. Track request counts per time window. When approaching the limit, queue requests or return a "rate limited -- retry after N seconds" message. This prevents the agent from burning through your API quota in a single reasoning loop.
6. Error mapping -- map API error responses to meaningful MCP errors. A 404 from the API should become a clear "resource not found" message, not a raw HTTP error dump. A 429 should tell the agent to wait. A 500 should indicate the external service is unavailable.

Testing and Debugging

1. Unit tests -- test each tool handler in isolation: valid inputs produce expected outputs, invalid inputs produce proper error responses, edge cases (empty strings, null values, maximum-length inputs) are handled. Mock external API calls so tests are fast and deterministic.
2. Protocol compliance -- test the JSON-RPC layer: initialize handshake works, capability advertisement is correct, unknown methods return MethodNotFound, malformed requests return ParseError. Use the MCP Inspector tool or write a minimal client that exercises the protocol.
3. Integration tests -- test the full flow: client connects, initializes, discovers tools, calls a tool, receives a response, disconnects. Test with actual API calls (using test/sandbox credentials) to verify end-to-end behavior. Test error paths: what happens when the API is down? When credentials are expired?
4. Transport testing -- for stdio: verify that the server handles stdin/stdout correctly and doesn't mix protocol messages with debug output (use stderr for logging). For SSE: test connection establishment, event streaming, reconnection after disconnect, and concurrent clients.
5. Load testing -- for SSE servers: test with multiple concurrent clients making simultaneous tool calls. Verify that the server handles concurrent requests without race conditions, data corruption, or excessive memory usage. Set connection limits and test behavior when limits are exceeded.
6. Client compatibility -- test your server with multiple MCP clients: Claude Desktop, Claude Code, and any other clients you support. Each client may have subtle differences in how it handles capabilities, error responses, or edge cases. Document any client-specific behaviors.

Output Format

SWITCHBLADE -- MCP SERVER SPECIFICATION
Server: [Server Name]
Transport: [stdio / SSE / both]
Tools: [N]  Resources: [N]  Prompts: [N]
Date: [YYYY-MM-DD]

=== TOOL DEFINITIONS ===
| Tool | Description | Parameters | Returns |
|------|-------------|-----------|---------|
| [name] | [description] | [param list] | [output type] |

=== INPUT SCHEMAS ===
Tool: [tool-name]
{
  "type": "object",
  "properties": {
    "[param]": { "type": "[type]", "description": "[desc]" }
  },
  "required": ["[param]"]
}

=== RESOURCE DEFINITIONS ===
| URI Pattern | Description | MIME Type |
|-------------|-------------|-----------|
| [pattern] | [description] | [type] |

=== TRANSPORT CONFIG ===
Protocol: JSON-RPC 2.0
Transport: [stdio config / SSE endpoint config]
Auth: [env var / header / none]

=== ERROR HANDLING ===
| Error Code | Meaning | When Returned |
|------------|---------|---------------|
| -32602 | InvalidParams | [scenario] |
| -32601 | MethodNotFound | [scenario] |
| -32603 | InternalError | [scenario] |

=== DEPLOYMENT ===
Runtime: [Node.js / Python]
Config: [environment variables]
Health Check: [endpoint or mechanism]

Common Pitfalls

• Logging to stdout on stdio transport -- the stdio transport uses stdout for JSON-RPC messages. If your server prints debug logs to stdout, it corrupts the protocol stream. Always log to stderr when using stdio transport. This is the number one cause of "my MCP server doesn't work" issues.
• Missing input descriptions -- tool parameters without descriptions are invisible to the LLM. It will guess what they mean or skip them entirely. Every parameter in your JSON Schema needs a clear, specific description.
• Overly broad tools -- a single tool that does everything ("manage-database" with 20 parameters) is harder for agents to use than specific tools ("query-records", "insert-record", "delete-record"). Follow the single-responsibility principle.
• Not handling initialization -- MCP requires an initialization handshake before tool calls. If your server processes tool calls before initialization, clients will reject the connection. Implement the full lifecycle.
• Returning raw API errors -- dumping a 500-line stack trace or raw HTTP error response into the tool output wastes context window and confuses the agent. Transform errors into concise, actionable messages.
• Ignoring content types -- MCP supports text and image content types in tool responses. Return structured text content with appropriate formatting. Don't return binary data as text or vice versa.

Guardrails

• Schema validation on all inputs. Every tool call is validated against its JSON Schema before execution. No input reaches your handler without passing validation. This prevents injection, type confusion, and unexpected behavior.
• No credentials in responses. Tool outputs are scanned for credential patterns (API keys, tokens, passwords) and redacted before returning to the client. Credentials live in environment variables, never in protocol messages.
• Timeout enforcement. Every tool handler has a configurable timeout. If the underlying operation (API call, database query, CLI execution) exceeds the timeout, the handler returns a timeout error rather than hanging indefinitely.
• Resource limits. Response sizes are capped. If a tool would return more than the configured maximum (default: 100KB of text), the response is truncated with a clear indication that truncation occurred. This prevents context window overflow on the client side.
• Transport security. SSE endpoints require authentication (API key header or OAuth token). Unauthenticated requests are rejected. Stdio servers inherit the security context of the parent process.
• No arbitrary code execution. Tool handlers execute predefined operations only. User inputs are never evaluated as code (no eval, no exec, no shell command injection). If your tool wraps a CLI, use parameterized commands with explicit argument validation.
• Graceful degradation. When an external dependency is unavailable, the server continues to function. Unavailable tools return clear error messages rather than crashing the entire server.

Support

Questions or issues with this skill? Contact brian@gorzelic.net Published by SpookyJuice -- https://www.shopclawmart.com