mcp-builder helps turn an existing API into tools an agent can discover and call. A successful protocol connection is only the beginning: useful tools need clear names, validated parameters, complete pagination, and errors that suggest a next step. This skill supports building an integration; it does not grant access to arbitrary external systems.
Install and invoke
Send these two commands in the Claude Code chat input, one at a time. They are plugin commands, not shell commands for your operating system. The second installs the official collection containing mcp-builder.
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills
In your project conversation, ask Claude to “use mcp-builder” and supply the task or files. The prompt below is an editable starting example. Installing the collection supplies instructions and resources; it does not supply your source material or guarantee that every runtime dependency is installed locally. If the skill is missing, check that its plugin is installed, enabled, and loaded in the current session. Do that before troubleshooting the requested output.
Start with a bounded read-only workflow
Use mcp-builder to create an MCP server for our knowledge-base API.
Read docs/api.md first. The first version should only search documents and read their details.
Use TypeScript and local stdio transport. Read credentials from environment variables.
Propose tool names, input/output schemas, and pagination before implementation.
Verify the server against test data.
Choose the service, language, and client connection model first. The skill recommends TypeScript and also provides a Python path. stdio suits a local subprocess, while remote service integration needs a transport such as Streamable HTTP and its associated deployment considerations. Confirm authentication, limits, and data models in the target API's own documentation.
Define search inputs, result limits, and next-page information. Define the identifier, content, and error cases for document retrieval. A service-prefixed name such as knowledge_search_documents helps avoid collisions when several servers are connected. Return enough information for the next action without sending the entire knowledge base. Filtering and pagination reduce unnecessary context.
Test engineering behavior and task usefulness
First check that the project builds, the client lists tools, valid and invalid inputs behave predictably, and missing credentials or upstream timeouts produce useful errors. With stdio, ordinary logs belong on standard error; standard output carries protocol messages. Read-only and idempotency annotations should match actual behavior, but are not access controls.
Next test whether a model can solve realistic questions using only these tools. Use a fixed historical window and a clearly comparable answer. Questions should be independent and read-only rather than relying on data written by an earlier question. A small representative set can reveal missing fields or pagination defects before expanding to the guide's ten-question evaluation.
The supplementary evaluation harness calls a model service and requires its own dependencies, credentials, and usable model configuration. Compiling the server does not establish that environment. Deliver source code, startup instructions, environment-variable names, a tool inventory, and actual test results. Keep real secrets out of example files. If answers omit information despite successful searches, inspect pagination, descriptions, and returned fields before adding more tools.
Design a tool around one real task
Start with a narrow request such as “retrieve the latest three invoices for a customer ID.” List the required parameters, API fields, pagination behavior, and authorization boundary. Have the agent design the tool name and input schema before writing the server. A huge raw JSON response can still hide the invoice status; return the relevant fields, cursor, and explainable errors.
Test at least a normal ID, a forbidden ID, and a customer requiring a second page. A successful protocol handshake checks only one layer. Inspect parameter validation, errors that might be mistaken for empty results, and whether the description helps an agent choose the right tool. The official workflow also calls for evaluation questions based on actual user requests that require a tool call, rather than tests that only start the server.
Treat authorization as part of tool design
If an API can both read public data and modify customer records, avoid one vague all-purpose tool. Separate read and write actions and describe the required identity, inputs, and consequences of each. Make “not found” distinct from “forbidden” in error responses. Test with an account that lacks permission and ensure the agent does not interpret a 403 as a nonexistent customer. Task-specific descriptions help the agent choose correctly and make write operations easier to review.
Separate evaluator setup from server behavior
If Phase 4 fails while connections.py imports streamablehttp_client, the server has not been tested yet. A public reproduction found that the example evaluator failed with MCP Python SDK 2.1.1 while 1.29.1 worked, due to an import-name change. Record the SDK version, traceback, and command; check imports in an isolated environment before changing the business logic of your MCP tools.