Building In-Process MCP Tools with the Claude Agent SDK

## Overview

Custom tools let Claude call your own functions during an Agent SDK session.
Using the SDK's in-process MCP server, you define tools with an input schema and
a handler, bundle them into a server that runs inside your application (not a
separate process), and pass them to `query`.

## Define a tool

A tool has a name, description, input schema, and async handler. Use the `tool()`
helper (TypeScript, Zod schema) or the `@tool` decorator (Python, dict or JSON
Schema), then wrap tools in a server.

```typescript
import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  { latitude: z.number(), longitude: z.number() },
  async (args) => ({ content: [{ type: "text", text: `...` }] }),
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});
```

Python uses `@tool(...)` and `create_sdk_mcp_server(...)` with the same shape.

## Register and allow the tool

Pass the server via `mcpServers`. The key becomes the `{server_name}` segment of
the fully qualified name `mcp__{server_name}__{tool_name}`; list that in
`allowedTools` so it runs without a prompt.

```typescript
for await (const message of query({
  prompt: "What's the temperature in San Francisco?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) { /* ... */ }
```

Use the wildcard `mcp__weather__*` to allow every tool a server exposes.

## Handle errors

Return `isError: true` (TS) / `"is_error": True` (Python) from the handler when a
call fails. The agent loop continues and Claude can retry or explain. An uncaught
exception stops the loop and fails the `query` call.

## Return images and structured data

A handler's `content` array accepts `text`, `image` (base64, no data URI prefix),
and `resource` blocks. Set `structuredContent` to return machine-readable JSON
alongside the content. (In Python, `structuredContent` requires a standalone MCP
server rather than the in-process `@tool` decorator.)

## Annotations and scaling

Pass annotations like `readOnlyHint: true` so Claude can batch parallel-safe
calls. Every tool definition consumes context each turn; for dozens of tools, use
tool search to load them on demand.

## Source

- Give Claude custom tools: https://code.claude.com/docs/en/agent-sdk/custom-tools
- Connect MCP servers: https://code.claude.com/docs/en/agent-sdk/mcp