Skip to content

server-side-tools.md

Latest commit

 

History

History
288 lines (222 loc) · 8.49 KB

server-side-tools.md

File metadata and controls

288 lines (222 loc) · 8.49 KB
Raw

Anthropic Server-Side Tools (reference)

Tools the Anthropic Messages API executes server-side: sent in the tools array of a request, with results streamed back as special content-block types.

This is a wire-format reference for the Anthropic provider. Klaudia ships its own local web search/fetch/browse tools (lazy headless Chrome — see the README), so it does not depend on these. On the Anthropic provider it can still enable the server-side web_search / web_fetch betas (pkg/agent/webtools.go); the shapes below document what those return.

Web Search

Tool types: Klaudia sends web_search_20260318 (current GA) with allowed_callers: ["direct"]. Older: web_search_20260209, web_search_20250305.

_20260209+ support dynamic filtering — running the search inside code execution to filter results before they reach the context. Klaudia pins direct instead: dynamic filtering nests results under a code_execution_tool_result (a different shape than the direct web_search_result blocks the recorder and citation repair handle) and 400s on pre-4.6 models. Enabling it is a deliberate follow-up (code-execution result handling + a model-capability gate + a live test).

Tool Definition (sent to API)

{
  "type": "web_search_20260209",
  "name": "web_search",
  "max_uses": 8,
  "allowed_domains": ["docs.example.com"],
  "blocked_domains": ["spam.com"]
}

allowed_domains and blocked_domains are optional, mutually exclusive at the tool-definition level. The model can also specify them per-call (dynamic filtering).

Model Input (what Claude sends)

{
  "query": "search terms here",
  "allowed_domains": ["example.com"],
  "blocked_domains": ["spam.com"]
}
  • query: string, min 2 chars, no wildcards (*, ?)
  • allowed_domains: optional string array
  • blocked_domains: optional string array
  • Cannot specify both domain filters in same call

Response

Content block type: web_search_tool_result

Success:

{
  "type": "web_search_tool_result",
  "tool_use_id": "toolu_...",
  "content": [
    { "title": "Page Title", "url": "https://example.com/page" },
    { "title": "Another Result", "url": "https://example.com/other" }
  ]
}

Error:

{
  "type": "web_search_tool_result",
  "tool_use_id": "toolu_...",
  "content": { "error_code": "rate_limited" }
}

Web Fetch

Tool types: Klaudia sends web_fetch_20260318 (current GA) with allowed_callers: ["direct"]. Older: web_fetch_20260209, web_fetch_20250910.

Tool Definition

{
  "type": "web_fetch_20260209",
  "name": "web_fetch"
}

Model Input

{
  "url": "https://example.com/page",
  "prompt": "Extract the main content from this page"
}
  • url: string, valid URL (HTTP auto-upgraded to HTTPS)
  • prompt: string, describes what to extract from the fetched content

Response

Content block type: web_fetch_tool_result

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "toolu_...",
  "content": {
    "url": "https://example.com/page",
    "code": 200,
    "codeText": "OK",
    "bytes": 45230,
    "durationMs": 1250,
    "result": "Extracted content based on the prompt..."
  }
}

Redirect handling: For 301/307/308, returns redirect target URL and asks the model to re-fetch with the new URL.

Code Execution

Tool type: code_execution_20260120

Server-side sandboxed execution. Automatically includes two sub-tools: bash_code_execution and text_editor_code_execution.

Tool Definition

{
  "type": "code_execution_20260120",
  "name": "code_execution"
}

Requires beta header: files-api-2025-04-14

Sub-Tool: bash_code_execution

The model writes bash/python code; Anthropic's servers execute it in a sandbox.

Sandbox environment:

  • Python 3.11 with: pandas, numpy, scipy, scikit-learn, matplotlib, seaborn, openpyxl, pillow, pypdf, pdfplumber, sympy, and more
  • 1 CPU, 5 GiB RAM, 5 GiB disk
  • No internet access
  • Containers persist 30 days

Response type: bash_code_execution_tool_result

{
  "type": "bash_code_execution_tool_result",
  "tool_use_id": "toolu_...",
  "content": {
    "type": "bash_code_execution_result",
    "return_code": 0,
    "stdout": "output here",
    "stderr": "",
    "content": []
  }
}

Sub-Tool: text_editor_code_execution

Server-side file create/view/edit operations within the sandbox.

Response type: text_editor_code_execution_tool_result

MCP (Model Context Protocol)

Klaudia's MCP is client-side, not a server-side tool: it connects to the servers in .mcp.json itself (stdio, streamable HTTP, or legacy SSE — see the README) and offers their tools to the model as ordinary tools named mcp__{server}__{tool} (rewritten to fit the API's 64-character [A-Za-z0-9_-] limit). A call is a plain tool_use, and the answer goes back as a plain tool_result — text, plus image blocks when the server returns images. Nothing goes through an Anthropic proxy.

The API's own MCP connector — the mcp_servers request parameter, with mcp_tool_use / mcp_tool_result blocks in the response (listed below for completeness) — is a different mechanism, in which Anthropic's servers call the MCP server. Klaudia does not use it.

Server config

~/.klaudia/.mcp.json, ./.mcp.json and ./.klaudia/.mcp.json, later files overriding earlier ones per server name:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {}
    },
    "remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer ..." }
    }
  }
}

Common Response Block Types

All content block types that can appear in streamed responses:

Type Source Purpose
text Model Claude's text response
thinking Model Extended thinking content
tool_use Model Client-side tool call request
server_tool_use Server Server-side tool invocation indicator
web_search_tool_result Server Search results
web_fetch_tool_result Server Fetched page content
bash_code_execution_tool_result Server Bash execution output
text_editor_code_execution_tool_result Server File operation results
code_execution_tool_result Server General code execution results
mcp_tool_use Server MCP connector tool call (API-side MCP; unused by Klaudia)
mcp_tool_result Server MCP connector tool result (unused by Klaudia)
tool_search_tool_result Server Tool discovery results
container_upload Server File upload indicator

Stop Reasons

Reason Meaning
end_turn Model finished responding
tool_use Model wants to call a client-side tool
pause_turn Server-side tool loop hit limit (max 10 iterations) — client should re-send to resume
max_tokens Hit token limit

Beta Headers

Server-side features are gated behind beta headers sent as anthropic-beta:

Beta Purpose
files-api-2025-04-14 File ops for code execution
web-search-2025-03-05 Web search capability
skills-2025-10-02 Skills feature
adaptive-thinking-2026-01-28 Extended/adaptive thinking
interleaved-thinking-2025-05-14 Interleaved thinking mode
structured-outputs-2025-11-13 Structured output format
ccr-byoc-2025-07-29 Customer Controlled Regions

How Klaudia covers these locally

Server-side tool Klaudia equivalent
Web Search Anthropic web_search server tool (preferred on Claude models, cited) with local BrowserSearch (lazy headless Chrome, DDG/Google) as the non-Claude fallback — internal/browser
Web Fetch Anthropic web_fetch server tool (preferred on Claude models) with local BrowserFetch / BrowserNavigate / BrowserSnapshot → Markdown as the fallback
MCP local stdio + HTTP/SSE MCP servers — internal/mcp
Code Execution container sandbox for the Bash tool (sandbox.mode = "container")
Browser Automation the local browser tools above; an MCP browser server can be registered for richer control

The Anthropic server-side web_search / web_fetch betas remain available when running on the Anthropic provider (pkg/agent/webtools.go). The local Browser tools are offered alongside them on every provider, not deferred: driving a real local Chrome is its own capability, and choosing between it and the server tools is the model's call (deferTool in internal/cli/root.go).