Skip to content
StTs

Strands Agents (TypeScript): Tools and MCP

Tools in the TypeScript Strands SDK: Zod tools with typed input, JSON Schema tools, tool context and per-request state, streaming tools, direct calls, executors, vended tools, sandboxes and MCP clients.

Checked against @strands-agents/sdk 1.24.0 (2026-11-19). Examples compile under tsc --strict and were run against an offline Bedrock stub; the MCP example ran against a real local stdio server.

tool() takes a name, a description, a Zod schema and a callback. The callback’s input is inferred from the schema, and the model’s arguments are validated before the callback runs. .describe() on each field becomes the parameter description the model reads:

import { Agent, tool } from '@strands-agents/sdk'
import { z } from 'zod'
const getOrderStatus = tool({
name: 'get_order_status',
description: 'Look up the shipping status of an order by its ID.',
inputSchema: z.object({
orderId: z.string().regex(/^ORD-\d+$/).describe('Order ID, e.g. ORD-1042'),
includeHistory: z.boolean().default(false).describe('Include past status changes'),
}),
callback: async ({ orderId, includeHistory }) => {
// input is typed as { orderId: string; includeHistory: boolean }
const status = { orderId, status: 'shipped', carrier: 'DPD' }
return includeHistory ? { ...status, history: ['created', 'packed', 'shipped'] } : status
},
})
const agent = new Agent({
model: 'us.anthropic.claude-sonnet-5-5',
tools: [getOrderStatus],
printer: false,
})
console.log((await agent.invoke('Where is order ORD-1042?')).toString())

Unlike Python, nested objects arrive as validated, typed values (Zod parses them), so a z.object parameter is safe to use directly.

Return values. Strings and numbers become a text block; objects and arrays become a JSON content block. Errors. If the callback throws, or validation fails, the model receives an error tool result and the loop continues.

The callback’s second argument is a ToolContext:

FieldContents
toolUseThe call (toolUseId, name, input)
agentThe calling agent (appState, messages, …)
invocationStateThe per-call state passed to invoke()
cancelSignalAn AbortSignal for cancellation; forward it to fetch and other APIs
interrupt({ name, reason })Pause for human input (interrupts)
import { Agent, tool } from '@strands-agents/sdk'
import type { ToolContext } from '@strands-agents/sdk'
import { z } from 'zod'
interface AppState {
tenantId: string
}
const listInvoices = tool({
name: 'list_invoices',
description: 'List recent invoices for the current tenant.',
inputSchema: z.object({ limit: z.number().int().min(1).max(50).default(10) }),
callback: async (input, context?: ToolContext) => {
if (!context) throw new Error('Tool context is required')
const tenantId = context.agent.appState.get<AppState>('tenantId') // durable state
const requestId = context.invocationState.requestId as string | undefined // per call
const response = await Promise.resolve({ invoices: [] as string[] }) // e.g. fetch(url, { signal: context.cancelSignal })
return { tenantId, requestId, limit: input.limit, ...response }
},
})
const agent = new Agent({
model: 'us.anthropic.claude-sonnet-5-5',
appState: { tenantId: 'acme' },
tools: [listInvoices],
printer: false,
})
await agent.invoke('Show my last five invoices.', { invocationState: { requestId: 'req-42' } })

Identity and authorisation data belongs in invocationState, where the model cannot see or change it.

A callback written as an async generator streams progress: each yield appears as a toolStreamUpdateEvent in agent.stream(), and the generator’s return value is the tool result (the last yielded value is not, unlike Python):

import { Agent, FunctionTool, tool } from '@strands-agents/sdk'
import { z } from 'zod'
const exportReport = tool({
name: 'export_report',
description: 'Export a report to PDF.',
inputSchema: z.object({ reportId: z.string() }),
callback: async function* (input): AsyncGenerator<string, string, unknown> {
yield 'Collecting data...'
yield 'Rendering PDF...'
return `s3://reports/${input.reportId}.pdf`
},
})
// Plain JSON Schema instead of Zod: input arrives as unknown
const ping = new FunctionTool({
name: 'ping',
description: 'Check that a host name resolves.',
inputSchema: { type: 'object', properties: { host: { type: 'string' } }, required: ['host'] },
callback: (input: unknown) => `ok: ${(input as { host: string }).host}`,
})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [exportReport, ping], printer: false })
for await (const event of agent.stream('Export report R-9')) {
if (event.type === 'toolStreamUpdateEvent') console.log('progress:', event.event.data)
}

ZodTool is the class behind tool(), and Tool is the abstract base for fully custom tools.

agent.tool.<name> gives a handle for calling a tool without the model. invoke() returns the ToolResultBlock; stream() yields progress first. Calls are recorded in the history (as an assistant tool use, the tool result and a short assistant note) unless you pass { recordDirectToolCall: false }:

import { Agent, tool } from '@strands-agents/sdk'
import { z } from 'zod'
const loadProfile = tool({
name: 'load_profile',
description: 'Load a user profile.',
inputSchema: z.object({ userId: z.string() }),
callback: ({ userId }) => ({ userId, name: 'Priya', plan: 'pro' }),
})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [loadProfile], printer: false })
const result = await agent.tool.load_profile!.invoke({ userId: 'u-17' })
console.log(result.status, JSON.stringify(result.content))
await agent.tool.load_profile!.invoke({ userId: 'u-18' }, { recordDirectToolCall: false })
console.log(agent.messages.length) // 3: the first call (tool use, result, and a note) was recorded; the second was not

Tool calls from one model turn run concurrently by default. To run them in order:

import { Agent, SequentialToolExecutor } from '@strands-agents/sdk'
const agent = new Agent({
model: 'us.anthropic.claude-sonnet-5-5',
toolExecutor: new SequentialToolExecutor(),
printer: false,
})

The SDK ships optional tools under @strands-agents/sdk/vended-tools/*. They are not loaded unless imported:

Import pathExports
vended-tools/shellmakeShell(sandbox?, options?) (makeBash is deprecated)
vended-tools/file-editorfileEditor, makeFileEditor
vended-tools/http-requesthttpRequest
vended-tools/web-fetchwebFetch, makeWebFetch (needs turndown)
vended-tools/notebooknotebook, makeNotebook
vended-tools/python-replpythonRepl, makePythonRepl
vended-tools/sleep, vended-tools/handoff-to-usersleep, handoffToUser
vended-tools/subagent, vended-tools/swarmLet the model spawn sub-agents
vended-tools/mcp-router, vended-tools/a2a-clientFactories for MCP routing and A2A calls
import { Agent } from '@strands-agents/sdk'
import { fileEditor } from '@strands-agents/sdk/vended-tools/file-editor'
import { httpRequest } from '@strands-agents/sdk/vended-tools/http-request'
import { makeShell } from '@strands-agents/sdk/vended-tools/shell'
const agent = new Agent({
model: 'us.anthropic.claude-sonnet-5-5',
tools: [makeShell(), fileEditor, httpRequest],
printer: false,
})
console.log(agent.tools.map((t) => t.name))

Shell, file and code tools run on the host unless the agent has a sandbox. DockerSandbox from @strands-agents/sdk/sandbox/docker (new DockerSandbox({ container, workingDir, user })) and an SSH sandbox from @strands-agents/sdk/sandbox/ssh route them elsewhere; pass one as the agent’s sandbox option.

There is no TypeScript strands-agents-tools package: the vended tools are the whole set. The Python package’s other tools (use_aws, retrieve, the AgentCore wrappers) were removed in 0.9 and have no TypeScript counterpart; write a Zod tool around the AWS SDK call you need.

McpClient connects to a Model Context Protocol server and exposes its tools. Install @modelcontextprotocol/client, and pass the client in tools; the agent connects and lists tools when it initialises (on the first invoke(), or await agent.initialize()).

This connects to the stdio inventory server from the Python MCP section (any MCP server works the same way), filters out one tool and prefixes the rest:

import { Agent, McpClient } from '@strands-agents/sdk'
import { StdioClientTransport } from '@modelcontextprotocol/client/stdio'
const inventory = new McpClient({
transport: new StdioClientTransport({ command: 'python3', args: ['inventory_server.py'] }),
toolFilters: { rejected: ['delete_sku'] },
prefix: 'inv',
})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [inventory], printer: false })
try {
await agent.initialize()
console.log(agent.tools.map((t) => t.name)) // [ 'inv_stock_level' ]
console.log((await agent.invoke('How many A-1 are in stock?')).toString())
} finally {
await inventory.disconnect()
}

For a Streamable HTTP server, pass url (and headers, or auth for OAuth client credentials, or authProvider):

import { Agent, McpClient } from '@strands-agents/sdk'
const internal = new McpClient({
url: 'https://mcp.example.com/mcp',
headers: { Authorization: `Bearer ${process.env.MCP_TOKEN ?? ''}` },
continueOnError: true, // start the agent even if this server is down
})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [internal], printer: false })

Other options: toolFilters (allowed / rejected lists of names, RegExps or callbacks), elicitationCallback, progressCallback, tasksConfig for long-running tools, logHandler. McpClient.loadServers(config) builds clients from an mcpServers-style JSON file or object. The client can also be used directly: listTools(), callTool(), listPrompts(), getPrompt(), listResources(), readResource(). AgentCore Gateway is an MCP server, reached the same way with an OAuth token.

DateVersionChanges
2026-10-241.22.0New page, from the tools and MCP sections of the TypeScript Strands page in the Amazon Bedrock guide. Adds tool context fields, the generator return-value rule, direct calls, executors, the vended tools table and sandboxes; MCP example run against a local stdio server.