---
title: セルフホスト型サンドボックスでのカスタムツール
url: https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-custom-tools
description: セルフホスト型サンドボックスのワーカーからカスタムツールを提供し、トンネルを実行せずにネットワーク内のMCPサーバーをカスタムツールとしてラップします。
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
[カスタムツール](https://platform.claude.com/docs/ja/managed-agents/tools#custom-tools)は、独自のコードが実行するツールです。エージェントは `agent.custom_tool_use` イベントを発行し、対応する `user.custom_tool_result` を待ちます。ワーカーがそのコードになることができます。ワーカーはサンドボックス内で実行されるため、ツールはサンドボックスに設定した内部サービス、認証情報、ネットワークの「egress」（エグレス）にアクセスでき、それ以外にはアクセスしません。
環境キーによってカスタムツールの結果の送信が認可されるため、Claude APIキーをワーカーホストに置く必要はありません。
カスタムツールを提供するにはSDKワーカーが必要です。`ant` CLIワーカーにはカスタムツールの実装を登録する手段がありません。セッションごとにサンドボックスを用意するパターンでは、[サンドボックス内でSDKワーカーを実行](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-workers#run-the-sdk-worker-inside-the-sandbox)してください。
## カスタムツールを提供する
エージェントの `tools` に `custom` エントリを追加し、その `name` をワーカーが登録するツールと一致させます。宣言の完全な形式については、[カスタムツール](https://platform.claude.com/docs/ja/managed-agents/tools#custom-tools)を参照してください。
```json
{
"type": "custom",
"name": "get_order_status",
"description": "Look up an order in the internal fulfillment system by order ID.",
"input_schema": {
"type": "object",
"properties": {
"order_id": { "type": "string", "description": "The order ID" }
},
"required": ["order_id"]
}
}
```
組み込みツールセットと並べて、ワーカーの `tools` (go: `ToolsFunc`) ファクトリ（[`EnvironmentWorker`](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-reference#environment-worker)を参照）を通じてツールを渡します。
```python Python
import asyncio
import os
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
@beta_async_tool
async def get_order_status(order_id: str) -> str:
"""Look up an order in the internal fulfillment system by order ID."""
# ワーカーホスト上で実行されます:サンドボックスから到達できるものは何でも呼び出せます。
return f"Order {order_id}: shipped"
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
async with AsyncAnthropic(auth_token=environment_key) as client:
await EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
tools=lambda env: [*beta_agent_toolset_20260401(env), get_order_status],
).run()
asyncio.run(main())
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema";
import { betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node";
const getOrderStatus = betaTool({
name: "get_order_status",
description: "Look up an order in the internal fulfillment system by order ID.",
inputSchema: {
type: "object",
properties: { order_id: { type: "string", description: "The order ID" } },
required: ["order_id"]
},
// ワーカーホスト上で実行されます：サンドボックスから到達可能なものは何でも呼び出せます。
run: async ({ order_id }) => `Order ${order_id}: shipped`
});
const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey });
const controller = new AbortController();
process.once("SIGTERM", () => controller.abort());
await new EnvironmentWorker({
client,
environmentId,
environmentKey,
workdir: "/workspace",
signal: controller.signal,
tools: (ctx) => [...betaAgentToolset20260401(ctx), getOrderStatus]
}).run();
```
C# SDKには`EnvironmentWorker`がありません。独自のコードからカスタムツール呼び出しに応答するには、[カスタムツールの結果を返す](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#return-a-custom-tool-result)のように、各結果をセッションのイベントストリームで送信してください。
```go Go
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/lib/environments"
"github.com/anthropics/anthropic-sdk-go/option"
"github.com/anthropics/anthropic-sdk-go/toolrunner"
"github.com/anthropics/anthropic-sdk-go/tools/agenttoolset"
)
type orderStatusInput struct {
OrderID string `json:"order_id"`
}
func main() {
environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
getOrderStatus := toolrunner.NewBetaTool(
"get_order_status",
"Look up an order in the internal fulfillment system by order ID.",
anthropic.BetaToolInputSchemaParam{
Properties: map[string]any{
"order_id": map[string]any{"type": "string", "description": "The order ID"},
},
Required: []string{"order_id"},
},
// ワーカーホスト上で実行：サンドボックスから到達可能なものを何でも呼び出せます。
func(ctx context.Context, input orderStatusInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
return anthropic.BetaToolResultBlockParamContentUnion{
OfText: &anthropic.BetaTextBlockParam{Text: "Order " + input.OrderID + ": shipped"},
}, nil
},
)
client := anthropic.NewClient(option.WithAuthToken(environmentKey))
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
EnvironmentID: environmentID,
EnvironmentKey: environmentKey,
Workdir: "/workspace",
ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
return append(agenttoolset.BetaAgentToolset20260401(env), getOrderStatus)
},
})
if err := worker.Run(ctx); err != nil {
log.Fatalf("worker: %v", err)
}
}
```
Java SDKには`EnvironmentWorker`がありません。独自のコードからカスタムツール呼び出しに応答するには、[カスタムツールの結果を返す](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#return-a-custom-tool-result)のように、各結果をセッションのイベントストリームで送信してください。
PHP SDKには`EnvironmentWorker`がありません。独自のコードからカスタムツール呼び出しに応答するには、[カスタムツールの結果を返す](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#return-a-custom-tool-result)のように、各結果をセッションのイベントストリームで送信してください。
Ruby SDKには`EnvironmentWorker`がありません。独自のコードからカスタムツール呼び出しに応答するには、[カスタムツールの結果を返す](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#return-a-custom-tool-result)のように、各結果をセッションのイベントストリームで送信してください。
ワーカーは、自身に登録されたツールにのみ応答します。エージェントでツールが宣言されているものの、それを提供するワーカーやクライアントが存在しない場合、セッションは `requires_action` の停止理由で一時停止します。何かが結果を送信するまで、セッションは一時停止したままになります。イベントの流れについては、[セッションを一時停止させるツール呼び出しに応答する](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session)を参照してください。
## MCPサーバーをカスタムツールとしてラップする
[MCPコネクタ](https://platform.claude.com/docs/ja/managed-agents/mcp-connector)は、Anthropic側からMCPサーバーに接続します。そのため、サーバーは、直接または[MCPトンネル](https://platform.claude.com/docs/ja/agents-and-tools/mcp-tunnels/overview)を介して、Anthropicが到達できるHTTPエンドポイントを公開する必要があります。
自社のネットワークからしか到達できないサーバーを使用するには、代わりにワーカーをMCPクライアントにし、サーバーのツールをカスタムツールとして宣言します。MCPサーバーには、ネットワーク外部からのインバウンド接続は必要ありません。Anthropicが受け取るのは、エージェントで宣言したツール定義、各呼び出しの入力、そしてワーカーが送り返す結果です。
実行時、モデルはラップされたツールを他のカスタムツールと同様に呼び出します。
1. エージェントが `agent.custom_tool_use` イベントを発行します。
2. サンドボックス内のワーカーが、開いているMCPセッションを介して、ネットワーク上のサーバーに呼び出しを転送します。
3. ワーカーがサーバーの応答を `user.custom_tool_result` として送信します。
### MCP SDKをインストールする
SDKの[クライアントサイドのMCPヘルパー](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#client-side-mcp-helpers)は、サーバーのツールをワーカーが受け付ける実行可能なツールに変換します。Anthropic SDKと併せてMCP SDKをインストールしてください：`pip install "anthropic[mcp]" "mcp>=1.24"` (typescript: `npm install @modelcontextprotocol/sdk`; go: `go get github.com/modelcontextprotocol/go-sdk`; csharp: `dotnet add package ModelContextProtocol`; java: `com.anthropic:anthropic-java-mcp`; php: `composer require mcp/sdk`; ruby: `bundle add mcp faraday event_stream_parser`)。
例では認証なしで接続しています。認証情報を送信するには、MCPトランスポートに渡す`http_client` (typescript: `requestInit`; go: `HTTPClient`; csharp: `AdditionalHeaders`; java: `customizeRequest`; php, ruby: `headers`)を設定してください。
### ツールを宣言して提供する
MCPサーバーのツールを一覧表示し、それぞれを `custom` ツールとして宣言します。MCPの `name`、`description`、`inputSchema` は、カスタムツールのフィールドに1対1で対応します。サーバーがツール一覧をページ分割している場合は、すべてのページを宣言してください。ワーカーも同じページを一覧表示する必要があります。
```python Python
import asyncio
from typing import Any, cast
from anthropic import AsyncAnthropic
from anthropic.types.beta import BetaManagedAgentsCustomToolParams
from mcp import ClientSession, types
# mcp >= 1.24 が必要です（streamablehttp_client が streamable_http_client に改名されました）。
from mcp.client.streamable_http import streamable_http_client
MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
def to_custom_tool(tool: types.Tool) -> BetaManagedAgentsCustomToolParams:
# MCPのフィールドはカスタムツール宣言に1対1で対応します。cast は
# スキーマ辞書をそのままSDKの型付きパラメータに渡します。
return {
"type": "custom",
"name": tool.name,
"description": tool.description or tool.name,
"input_schema": cast(Any, tool.inputSchema),
}
async def main() -> None:
# これはワーカーホストではなく、エージェントを作成する場所で実行してください。
# Claude APIキー（ANTHROPIC_API_KEY）で認証します。
async with (
streamable_http_client(MCP_SERVER_URL) as (read, write, _),
ClientSession(read, write) as mcp_session,
AsyncAnthropic() as client,
):
await mcp_session.initialize()
listed = await mcp_session.list_tools()
agent = await client.beta.agents.create(
name="Internal tools agent",
model="claude-opus-5-5",
tools=[
{"type": "agent_toolset_20260401"},
*[to_custom_tool(tool) for tool in listed.tools],
],
)
print(agent.id)
asyncio.run(main())
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp";
// これはワーカーホスト上ではなく、エージェントを作成する場所で実行してください:
// Claude APIキー(ANTHROPIC_API_KEY)で認証を行います。
const client = new Anthropic();
const mcpClient = new Client({ name: "declare-agent-tools", version: "1.0.0" });
await mcpClient.connect(new StreamableHTTPClientTransport(new URL(MCP_SERVER_URL)));
const { tools } = await mcpClient.listTools();
const agent = await client.beta.agents.create({
name: "Internal tools agent",
model: "claude-opus-5-5",
tools: [
{ type: "agent_toolset_20260401" },
// MCPの各フィールドはカスタムツール宣言に1対1で対応します。
...tools.map((tool) => ({
type: "custom" as const,
name: tool.name,
description: tool.description || tool.name,
input_schema: tool.inputSchema
}))
]
});
console.log(agent.id);
await mcpClient.close();
```
```csharp C#
using System.Text.Json;
using Anthropic;
using Anthropic.Models.Beta.Agents;
using ModelContextProtocol.Client;
const string McpServerUrl = "http://mcp.internal.example.com:8000/mcp";
// これはワーカーホスト上ではなく、エージェントを作成する場所で実行してください:
// Claude APIキー（ANTHROPIC_API_KEY）で認証するためです。
var client = new AnthropicClient();
await using var mcpClient = await McpClient.CreateAsync(
new HttpClientTransport(new HttpClientTransportOptions { Endpoint = new Uri(McpServerUrl) })
);
var mcpTools = await mcpClient.ListToolsAsync();
List tools =
[
new BetaManagedAgentsAgentToolset20260401Params { Type = "agent_toolset_20260401" },
];
foreach (var tool in mcpTools)
{
var description = tool.Description;
if (string.IsNullOrEmpty(description))
{
description = tool.Name;
}
// MCP のフィールドはカスタムツール宣言に一対一で対応します。
// スキーマのキーワードはそのまま SDK に渡されます。
tools.Add(
new BetaManagedAgentsCustomToolParams
{
Type = "custom",
Name = tool.Name,
Description = description,
InputSchema = new(
tool.ProtocolTool.InputSchema.Deserialize>()!
),
}
);
}
var agent = await client.Beta.Agents.Create(new()
{
Name = "Internal tools agent",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
Tools = tools,
});
Console.WriteLine(agent.ID);
```
```go Go
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
const mcpServerURL = "http://mcp.internal.example.com:8000/mcp"
// toCustomTool は1つのMCPツール定義をカスタムツール宣言にマッピングします。
// フィールドは1対1で対応します：型付きパラメータが `properties` と
// `required` を保持し、サーバーが出力するその他すべてのJSON Schemaキーワードは
// ExtraFields に格納されるため、宣言されたスキーマはサーバーのスキーマと一致します。
func toCustomTool(tool *mcpsdk.Tool) (anthropic.BetaAgentNewParamsToolUnion, error) {
raw, err := json.Marshal(tool.InputSchema)
if err != nil {
return anthropic.BetaAgentNewParamsToolUnion{}, err
}
var schema map[string]any
if err := json.Unmarshal(raw, &schema); err != nil {
return anthropic.BetaAgentNewParamsToolUnion{}, err
}
inputSchema := anthropic.BetaManagedAgentsCustomToolInputSchemaParam{ExtraFields: map[string]any{}}
for keyword, value := range schema {
switch keyword {
case "type":
// パラメータ型は常に "type": "object" としてマーシャルされます。
case "properties":
properties, _ := value.(map[string]any)
inputSchema.Properties = properties
case "required":
entries, _ := value.([]any)
for _, entry := range entries {
if name, isString := entry.(string); isString {
inputSchema.Required = append(inputSchema.Required, name)
}
}
default:
inputSchema.ExtraFields[keyword] = value
}
}
description := tool.Description
if description == "" {
description = tool.Name
}
return anthropic.BetaAgentNewParamsToolUnion{
OfCustom: &anthropic.BetaManagedAgentsCustomToolParams{
Type: anthropic.BetaManagedAgentsCustomToolParamsTypeCustom,
Name: tool.Name,
Description: description,
InputSchema: inputSchema,
},
}, nil
}
func main() {
ctx := context.Background()
// これはワーカーホスト上ではなく、エージェントを作成する場所で実行してください：
// Claude APIキー（ANTHROPIC_API_KEY）で認証します。
client := anthropic.NewClient()
mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "declare-agent-tools", Version: "1.0.0"}, nil)
session, err := mcpClient.Connect(ctx, &mcpsdk.StreamableClientTransport{Endpoint: mcpServerURL}, nil)
if err != nil {
log.Fatalf("connect to MCP server: %v", err)
}
defer session.Close()
listed, err := session.ListTools(ctx, nil)
if err != nil {
log.Fatalf("list MCP tools: %v", err)
}
tools := []anthropic.BetaAgentNewParamsToolUnion{
{OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
}},
}
for _, tool := range listed.Tools {
custom, err := toCustomTool(tool)
if err != nil {
log.Fatalf("convert MCP tool %s: %v", tool.Name, err)
}
tools = append(tools, custom)
}
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Internal tools agent",
Model: anthropic.BetaManagedAgentsModelConfigParams{ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5},
Tools: tools,
})
if err != nil {
log.Fatalf("create agent: %v", err)
}
fmt.Println(agent.ID)
}
```
```java Java
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.agents.AgentCreateParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params;
import com.anthropic.models.beta.agents.BetaManagedAgentsCustomToolInputSchema;
import com.anthropic.models.beta.agents.BetaManagedAgentsCustomToolParams;
import com.anthropic.models.beta.agents.BetaManagedAgentsModel;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.HttpClientStreamableHttpTransport;
import io.modelcontextprotocol.spec.McpSchema;
// MCP のフィールドはカスタムツール宣言に一対一で対応します。MCP Java
// SDK はツールの入力スキーマのうち、次のトップレベルキーワードのみを保持します：type、
// properties、required、additionalProperties、$defs、definitions。
BetaManagedAgentsCustomToolParams toCustomTool(McpSchema.Tool tool) {
var description = tool.description();
if (description == null || description.isEmpty()) {
description = tool.name();
}
return BetaManagedAgentsCustomToolParams.builder()
.type(BetaManagedAgentsCustomToolParams.Type.CUSTOM)
.name(tool.name())
.description(description)
.inputSchema(JsonValue.from(tool.inputSchema())
.convert(BetaManagedAgentsCustomToolInputSchema.class))
.build();
}
void main() {
// これはワーカーホスト上ではなく、エージェントを作成する場所で実行してください：
// Claude APIキー（ANTHROPIC_API_KEY）で認証を行います。
var client = AnthropicOkHttpClient.fromEnv();
// MCP サーバーのアドレスと、その MCP エンドポイントのパスです。
var transport = HttpClientStreamableHttpTransport.builder("http://mcp.internal.example.com:8000")
.endpoint("/mcp")
.build();
try (var mcpClient = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("declare-agent-tools", "1.0.0"))
.build()) {
mcpClient.initialize();
var params = AgentCreateParams.builder()
.name("Internal tools agent")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.addTool(BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build());
for (var tool : mcpClient.listTools().tools()) {
params.addTool(toCustomTool(tool));
}
var agent = client.beta().agents().create(params.build());
IO.println(agent.id());
}
}
```
```php PHP
use Anthropic\Beta\Agents\BetaManagedAgentsModel;
use Anthropic\Client as Anthropic;
use Mcp\Client as McpClient;
use Mcp\Client\Transport\HttpTransport;
$mcpServerUrl = 'http://mcp.internal.example.com:8000/mcp';
// これはワーカーホストではなく、エージェントを作成する場所で実行してください：
// Claude APIキー（ANTHROPIC_API_KEY）で認証するためです。
$client = new Anthropic();
$mcpClient = McpClient::builder()->build();
$mcpClient->connect(new HttpTransport($mcpServerUrl));
$tools = [['type' => 'agent_toolset_20260401']];
foreach ($mcpClient->listTools()->tools as $tool) {
// MCP のフィールドはカスタムツール宣言に一対一で対応します。
// スキーマのキーワードはそのまま SDK に渡されます。
$tools[] = [
'type' => 'custom',
'name' => $tool->name,
'description' => $tool->description ?: $tool->name,
'inputSchema' => $tool->inputSchema,
];
}
$agent = $client->beta->agents->create(
name: 'Internal tools agent',
model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
tools: $tools,
);
echo $agent->id, "\n";
$mcpClient->disconnect();
```
```ruby Ruby
require "anthropic"
require "mcp"
MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
# これはワーカーホストではなく、エージェントを作成する場所で実行してください：
# Claude APIキー（ANTHROPIC_API_KEY）で認証するためです。
client = Anthropic::Client.new
transport = MCP::Client::HTTP.new(url: MCP_SERVER_URL)
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
custom_tools = mcp_client.tools.map do |tool|
description = tool.description
description = tool.name if description.nil? || description.empty?
# MCP のフィールドはカスタムツール宣言に一対一で対応します。
# スキーマのキーワードはそのまま SDK に渡されます。
{
type: :custom,
name: tool.name,
description: description,
input_schema: tool.input_schema
}
end
agent = client.beta.agents.create(
name: "Internal tools agent",
model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
tools: [{type: :agent_toolset_20260401}, *custom_tools]
)
puts agent.id
transport.close
```
起動時に同じMCPサーバーに接続し、`async_mcp_tool` (typescript: `mcpTools`; go: `mcp.NewBetaTools`) でそのツールを変換して、`beta_agent_toolset_20260401` (typescript: `betaAgentToolset20260401`; go: `agenttoolset.BetaAgentToolset20260401`) と並べて登録します。ワーカーが稼働している間は、1つのMCPセッションを開いたままにしてください。
```python Python
import asyncio
import os
from datetime import timedelta
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_agent_toolset_20260401
from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
# mcp >= 1.24 が必要です(streamablehttp_client が streamable_http_client に改名されました)。
from mcp.client.streamable_http import streamable_http_client
MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp"
async def main() -> None:
environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
# 起動時に一度だけ MCP サーバーに接続し、ワーカーの存続期間中は
# セッションを開いたままにします。タイムアウトにより、ハングしたツール呼び出しは
# 停止したままになるのではなくエラー結果として返されます。
async with (
streamable_http_client(MCP_SERVER_URL) as (read, write, _),
ClientSession(
read, write, read_timeout_seconds=timedelta(seconds=60)
) as mcp_session,
AsyncAnthropic(auth_token=environment_key) as client,
):
await mcp_session.initialize()
listed = await mcp_session.list_tools()
mcp_tools = [async_mcp_tool(tool, mcp_session) for tool in listed.tools]
await EnvironmentWorker(
client,
environment_id=environment_id,
environment_key=environment_key,
workdir="/workspace",
tools=lambda env: [*beta_agent_toolset_20260401(env), *mcp_tools],
).run()
asyncio.run(main())
```
```typescript TypeScript
import Anthropic from "@anthropic-ai/sdk";
import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
import {
mcpTools,
type MCPCallToolResultLike,
type MCPClientLike
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const MCP_SERVER_URL = "http://mcp.internal.example.com:8000/mcp";
const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
const client = new Anthropic({ authToken: environmentKey });
const controller = new AbortController();
process.once("SIGTERM", () => controller.abort());
// 起動時に一度だけMCPサーバーに接続し、ワーカーの存続期間中は
// 接続を開いたままにします。
const mcpClient = new Client({ name: "sandbox-worker", version: "1.0.0" });
await mcpClient.connect(new StreamableHTTPClientTransport(new URL(MCP_SERVER_URL)));
const { tools } = await mcpClient.listTools();
// MCP SDK の callTool の戻り値型には、mcpTools が受け付けないレガシーな結果の形が
// 依然として含まれるため、型を絞り込みます。MCPClientLike が拡張されたら削除してください。
const mcpClientForTools: MCPClientLike = {
callTool: (params) => mcpClient.callTool(params) as Promise
};
await new EnvironmentWorker({
client,
environmentId,
environmentKey,
workdir: "/workspace",
signal: controller.signal,
tools: (ctx) => [...betaAgentToolset20260401(ctx), ...mcpTools(tools, mcpClientForTools)]
}).run();
```
C# SDKには`EnvironmentWorker`がありません。
```go Go
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/lib/environments"
"github.com/anthropics/anthropic-sdk-go/mcp"
"github.com/anthropics/anthropic-sdk-go/option"
"github.com/anthropics/anthropic-sdk-go/tools/agenttoolset"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
const mcpServerURL = "http://mcp.internal.example.com:8000/mcp"
func main() {
environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY")
environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID")
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
client := anthropic.NewClient(option.WithAuthToken(environmentKey))
// 起動時に一度だけMCPサーバーに接続し、ワーカーの存続期間中は
// セッションを開いたままにします。
mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "sandbox-worker", Version: "1.0.0"}, nil)
session, err := mcpClient.Connect(ctx, &mcpsdk.StreamableClientTransport{Endpoint: mcpServerURL}, nil)
if err != nil {
log.Fatalf("connect to MCP server: %v", err)
}
defer session.Close()
listed, err := session.ListTools(ctx, nil)
if err != nil {
log.Fatalf("list MCP tools: %v", err)
}
mcpTools, err := mcp.NewBetaTools(listed.Tools, session)
if err != nil {
log.Fatalf("convert MCP tools: %v", err)
}
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
EnvironmentID: environmentID,
EnvironmentKey: environmentKey,
Workdir: "/workspace",
ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
return append(agenttoolset.BetaAgentToolset20260401(env), mcpTools...)
},
})
if err := worker.Run(ctx); err != nil {
log.Fatalf("worker: %v", err)
}
}
```
Java SDKには`EnvironmentWorker`がありません。
PHP SDKには`EnvironmentWorker`がありません。
Ruby SDKには`EnvironmentWorker`がありません。
## 制限と動作
### ツールは宣言されるものであり、実行時に検出されるものではない
ワーカーは起動時に一度だけMCPサーバーのツールを一覧表示し、実行中のセッションにツールを追加することはできません。サーバーのツールが変更された場合は、次の手順を実行します。
1. エージェントで、または[エージェント設定の更新](https://platform.claude.com/docs/ja/managed-agents/session-operations#updating-the-agent-configuration)を通じてアイドル状態のセッションで、ツールを再度宣言します。
2. ワーカーを再起動します。
### 宣言はManaged Agents APIに適合している必要がある
MCPヘルパーはサーバーの名前と説明を保持し、ほとんどのスキーマは変更されずにそのまま渡されます。宣言が次のいずれかのルールに違反する場合は、名前の変更、切り詰め、またはインライン化を行ってください。
| フィールド | ルール |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | エージェントごとに一意。英字、数字、アンダースコア、ハイフンで構成され、1〜128文字。`bash` や `read` などの組み込みエージェントツールと一致させたり、予約済みの `mcp__` プレフィックスや `ant__` プレフィックスを使用したりすることはできません。 |
| `description` | 必須で、空にはできません。 |
| `input_schema` | `additionalProperties` や `title` など、MCPサーバーが一般的に出力するJSON Schemaキーワードを受け付けます。`$ref` などの参照キーワードはどこにあっても拒否され、トップレベルの `oneOf`、`anyOf`、`allOf` も拒否されます。プロパティ名には英字、数字、アンダースコア、ドット、ハイフンを使用し、1〜64文字です。 |
| エージェントの `tools` 配列 | 最大256エントリ。ラップされた各ツールが1エントリとなり、組み込みツールセットがさらに1エントリとなります。 |
次の2つのケースでは追加の作業が必要です。
* **2つのサーバーが同じツール名を公開している場合：** プレフィックス付きの名前でラッパーを自分で定義し、そのラッパーからサーバーの元のツール名を呼び出すようにします。
* **pydanticなどのジェネレーターがスキーマを `$defs` に分解している場合：** ツールを宣言する前に、それらのスキーマをインライン化します。
### ツールの失敗はエラーのツール結果として表面化する
MCPサーバーがツールエラーを報告すると、ワーカーはモデルが対応できるエラーのツール結果を送信します。オーディオブロックやリソースリンクなど、ツール結果に相当するものがないMCPコンテンツも、エラーとして表面化します。
Pythonワーカーの例で `read_timeout_seconds` を使用しているように、MCPクライアントにタイムアウトを設定すると、より迅速かつ明確に失敗させることができます。タイムアウトがない場合に何が起こるかについては、[ラップされたMCPツール呼び出しがハングする](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-operations#a-wrapped-mcp-tool-call-hangs)を参照してください。
### 自社で運用しているか信頼できるサーバーのみをラップする
ラップされたツールの名前、説明、結果は、他のツールと同様にモデルのコンテキストに入ります。これらは信頼できない入力であり、ワーカーホスト上の `bash` を含め、エージェントが他のツールで行う動作に影響を与える可能性があります。エージェントに使用させるつもりのツールのみを宣言してください。
### 権限ポリシーは適用されない
[権限ポリシー](https://platform.claude.com/docs/ja/managed-agents/permission-policies#custom-tools)は、組み込みツールセットとMCPツールセットを管理します。ワーカーはモデルが行うラップされたツール呼び出しをすべて実行するため、承認ステップが必要な場合は独自のツールコードに組み込んでください。