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, register it as an in-process SDK MCP server, and approve it by its mcp__server__tool name
- Write the guardrail each kind of tool needs: SQL, HTTP, filesystem and shell
- Return errors the model can recover from, and mark read-only tools so they run in parallel
28
Custom Tools: @tool and SDK MCP Servers
A custom tool is an async function with a name, a description and a schema. You wrap it in an MCP server that lives in your own process, and the agent calls it like any built-in.
Key idea
Define the function with @tool, wrap it with create_sdk_mcp_server, pass it in mcp_servers, and approve it as mcp__<key>__<tool>. The model picks the arguments, so every tool body treats them as untrusted and returns errors the model can act on.
Same protocol, two places to run it: your tool in your process, or a server you run beside it