Custom Tools: @tool and SDK MCP Servers
Build custom Claude Agent SDK tools with @tool and create_sdk_mcp_server, get the mcp__server__tool naming right, and see four production tools — SQL, HTTP, filesystem, shell — with the guardrail each needs.
Last updated
After this section you can
- Define a custom tool and register it as an in-process SDK MCP server
- Get the mcp__server__tool naming right so the tool is actually reachable
- Write the guardrail each class of tool needs — SQL, HTTP, filesystem, shell
- Return errors the model can recover from instead of stack traces
35
Custom Tools: @tool and SDK MCP Servers
A tool is an async function with a name, a description and a schema. Three lines register it, and it runs inside your own process — same imports, same connection pool, same stack trace.
THE CENTRAL IDEA
Custom tools are MCP servers that never leave your process. You get the protocol — discovery, schemas, namespacing — without a subprocess to supervise. The description is the part the model actually reads, so it is the part worth writing carefully.