langchain-claude-code / claude-sdk

---
description: @tool decorator, create_sdk_mcp_server for in-process custom MCP tools
alwaysApply: false
---

# Custom Tools (In-Process MCP Servers)

Create custom tools that run in-process, eliminating subprocess overhead.

## Benefits Over External MCP Servers

✓ No subprocess management - runs in same process
✓ Better performance - no IPC overhead
✓ Simpler deployment - single Python process
✓ Easier debugging - all code in one process
✓ Type safety - direct Python function calls

## Creating Tools

```python
from typing import Any
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

# 1. Define tool with @tool decorator
@tool("greet", "Greet a user", {"name": str})
async def greet_user(args: dict[str, Any]) -> dict[str, Any]:
    return {
        "content": [{"type": "text", "text": f"Hello, {args['name']}!"}]
    }

# 2. Create MCP server
server = create_sdk_mcp_server(
    name="my-tools",
    version="1.0.0",
    tools=[greet_user]
)

# 3. Configure options (CRITICAL: add to allowed_tools)
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]  # mcp__{server}__{tool}
)
```

## Tool Naming Convention

**Pattern**: `mcp__{server_name}__{tool_name}`

```python
# Server named "calc" with tool named "add"
allowed_tools=["mcp__calc__add"]

# Server named "my-tools" with tool named "greet"
allowed_tools=["mcp__my-tools__greet"]
```

## Complete Calculator Example

```python
from typing import Any
from claude_agent_sdk import (
    tool,
    create_sdk_mcp_server,
    ClaudeAgentOptions,
    ClaudeSDKClient,
)

@tool("add", "Add two numbers", {"a": float, "b": float})
async def add_numbers(args: dict[str, Any]) -> dict[str, Any]:
    result = args["a"] + args["b"]
    return {
        "content": [{"type": "text", "text": f"{args['a']} + {args['b']} = {result}"}]
    }

@tool("divide", "Divide two numbers", {"a": float, "b": float})
async def divide_numbers(args: dict[str, Any]) -> dict[str, Any]:
    if args["b"] == 0:
        return {
            "content": [{"type": "text", "text": "Error: Division by zero"}],
            "is_error": True,
        }
    result = args["a"] / args["b"]
    return {
        "content": [{"type": "text", "text": f"{args['a']} ÷ {args['b']} = {result}"}]
    }

calculator = create_sdk_mcp_server(
    name="calc",
    version="1.0.0",
    tools=[add_numbers, divide_numbers],
)

options = ClaudeAgentOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__divide"],
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Calculate 15 + 27")
    async for msg in client.receive_response():
        print(msg)
```

## Tool Return Format

Tools return a dict with `content` array:

```python
# Success
return {
    "content": [{"type": "text", "text": "Result message"}]
}

# Error
return {
    "content": [{"type": "text", "text": "Error description"}],
    "is_error": True,
}
```

## Mixed Server Support

Combine SDK (in-process) and external (subprocess) MCP servers:

```python
options = ClaudeAgentOptions(
    mcp_servers={
        "internal": sdk_server,       # In-process SDK server
        "external": {                  # External subprocess server
            "type": "stdio",
            "command": "external-server"
        }
    }
)
```

## Migration from External Servers

```python
# BEFORE: External MCP server (separate process)
options = ClaudeAgentOptions(
    mcp_servers={
        "calculator": {
            "type": "stdio",
            "command": "python",
            "args": ["-m", "calculator_server"]
        }
    }
)

# AFTER: SDK MCP server (in-process)
calculator = create_sdk_mcp_server(
    name="calculator",
    tools=[add, subtract]
)
options = ClaudeAgentOptions(
    mcp_servers={"calculator": calculator}
)
```

## Pitfall: Missing allowed_tools

Registering a server is insufficient. Tools must be explicitly allowed:

```python
# ✗ WRONG: Tool registered but not allowed
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    # Missing allowed_tools!
)

# ✓ CORRECT: Tool registered AND allowed
options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)
```