How to use the MCP Server Builder agent skill (mcp-builder)

What does the mcp-builder skill make the agent do?

Once installed, the agent follows the skill's guidance when you are building an MCP server or MCP tools. The guide covers three MCP building blocks: Tools (functions the assistant calls, which can have side effects), Resources (read-only data identified by a URI), and Prompts (predefined interaction templates). It also gives rules for naming and describing tools, validating inputs with Zod or Pydantic, handling errors, managing resources and lifecycle, writing unit and integration tests, debugging with the MCP Inspector, and packaging for npm, pip or Docker.

The file itself is written guidance and code templates. It does not run anything on its own.

• Tool names in snake_case that start with a verb, such as search_users or create_issue
• Input validation at the schema level, plus business checks at the start of each handler
• Error responses that set isError: true and explain what went wrong
• Security practices such as environment variables for secrets, parameterised queries and execFile instead of exec

How do you install the mcp-builder skill?

Download the ZIP file from this page and unzip it. You can put the skill in one of two places:

• Personal install: unzip into ~/.claude/skills/ so it is available across your projects.
• Project install: unzip into the .claude/skills/ folder inside a specific project.
• Claude apps: upload the skill under Settings → Capabilities → Skills.

How do you trigger the skill with a natural request?

You do not need a special command. Describe the MCP work you want in plain language while the skill is installed. The skill is meant for building or debugging a server, not for connecting to one that already exists. Requests such as the following should match its purpose:

• "Help me build an MCP server in TypeScript that wraps our internal ticket API."
• "Design the tools for an MCP server that searches and creates support issues."
• "My MCP server doesn't show up in the client. Help me debug it."
• "Set up unit and integration tests for my MCP server and check it with the Inspector."
• "Package this MCP server for npm and write the client configuration example."

What do you need before you start?

The skill assumes a working toolchain for the language you choose. The source lists these requirements:

• Node.js or a Python toolchain, depending on your language
• TypeScript projects: @modelcontextprotocol/sdk and zod
• Python projects: mcp and pydantic
• MCP Inspector, run through npx, for interactive testing
• Docker, only if you use the Docker deployment option

What does a typical build look like?

The guide suggests a project layout (src/ with index.ts and folders for tools, resources and lib, plus tests/ and package.json for TypeScript; src/my_mcp_server/ with server.py, pyproject.toml for Python). It recommends writing business logic as plain exported functions and keeping MCP registration separate, so the logic can be tested directly.

For debugging, the guide warns that MCP uses stdio for communication, so console.log can break the protocol stream. Use console.error or the SDK's logging instead. Its troubleshooting table covers common symptoms: no response at startup (check server.connect()), a tool that does not appear (register tools before connect), the assistant not calling a tool (improve the name and description), wrong parameters (add .describe()), and timeouts (add timeouts and caching).

• Debug order from the guide: verify basics in the Inspector, call tools manually to check inputs and outputs, connect a real AI client to observe calls, then adjust the design.

What safety points should you know about?

The skill does not run scripts and does not use the network. It is guidance that the agent applies to the code it writes. The skill itself lists good practices but does not audit any specific code, so you still need your own review before production use.

The guidance covers least privilege, separating read and write tools, requiring explicit confirmation parameters for dangerous actions, restricting file paths, using allow-lists for network requests, reading secrets from environment variables, and avoiding logging sensitive data.