Give Claude Custom Tools with MCP

Claude Agent SDK custom tools are MCP tools created in your Python or TypeScript process and attached as an SDK MCP server. Their names use mcp__server__tool, and they still require permission configuration. Typed schemas improve arguments; annotations describe behavior; neither replaces authorization, tenant scope, timeout, or side-effect controls.

What will you be able to do?

You will create a read-only ticket tool, register it in-process, and auto-approve only its exact MCP name.

How do you create the tool?

custom_tool.py:

python

import asyncio
from typing import Any

from claude_agent_sdk import (
    ClaudeAgentOptions,
    ToolAnnotations,
    create_sdk_mcp_server,
    query,
    tool,
)


@tool(
    "get_ticket",
    "Return one fictional support ticket by ID",
    {"ticket_id": str},
    annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=False),
)
async def get_ticket(args: dict[str, Any]) -> dict[str, Any]:
    ticket_id = args["ticket_id"]
    if ticket_id != "T-100":
        return {"content": [{"type": "text", "text": "Ticket not found"}]}
    return {
        "content": [
            {"type": "text", "text": "T-100: Duplicate charge; status=open"}
        ]
    }


server = create_sdk_mcp_server(
    name="supportops",
    version="1.0.0",
    tools=[get_ticket],
)


async def main() -> None:
    options = ClaudeAgentOptions(
        mcp_servers={"supportops": server},
        allowed_tools=["mcp__supportops__get_ticket"],
        disallowed_tools=["Bash", "Edit", "Write"],
        max_turns=4,
    )
    async for message in query(prompt="Summarize T-100.", options=options):
        print(type(message).__name__)


if __name__ == "__main__":
    asyncio.run(main())

In a real application, authenticated tenant context should be captured by the host or gateway, not accepted from model arguments. Confirm the installed SDK’s context/dependency pattern before implementation.

How do remote MCP servers differ?

External stdio or HTTP servers run outside the application process and expand the supply chain, network, credential, and lifecycle boundary. Pin versions, filter tools, pass minimal credentials, restrict egress, set connection/tool deadlines, and treat outputs as untrusted.

How do you prove it works?

Test the handler directly, then verify the agent calls only the fully qualified tool. Remove it from allowed_tools and confirm permission handling. Return malicious instruction text and ensure no subsequent proposal bypasses policy.

Failure injection: Mark a mutating tool readOnlyHint=True. Security must not change. Annotations are planning/client hints, not enforcement.

What mistakes should you avoid?

Allowing mcp__server__* when one exact tool suffices.
Returning secrets in text content.
Trusting annotations as permission.
Accepting tenant identity from tool arguments.
Forgetting remote MCP lifecycle and credential isolation.

Check your understanding

How is a custom tool named in allowed_tools?
What do tool annotations provide?
Which new risks appear with external MCP servers?

Expert extension

Add a mutating proposal tool and separate commit tool. Implement exact-name permissions, idempotency, approval, and result redaction through a host policy layer.

Official references