Skip to main content
Toolshed is a framework for building Model Context Protocol (MCP) tool servers that AI agents can discover and invoke. You define tools in TypeScript using the Toolshed SDK, connect them to external services through plugins and sources, control which agents can access which tools through a policy layer, and expose everything over a standard MCP interface — all from a single platform.

​
What you can build

Toolshed is designed for teams who need production-grade MCP servers: typed tool definitions with validated inputs and outputs, auth-aware integrations with third-party APIs, role-based access control, and human-in-the-loop approval flows for destructive operations.

Quickstart

Install the CLI and SDK, define your first plugin, and start an MCP server in minutes.

Plugins

Learn how to define tools and plugins using definePlugin() and defineTool() with full TypeScript type safety.

Sources

Auto-generate tools from OpenAPI specs, GraphQL endpoints, or existing MCP servers — no handlers required.

Policy

Create agent roles with wildcard tool path patterns to enforce least-privilege access across your tool catalog.

​
Core concepts

​
Plugins

A plugin is the primary unit of tool authorship in Toolshed. You define a plugin with definePlugin() from @toolshed/sdk, giving it an id, name, and a list of tools built with defineTool(). Each tool declares a Zod input schema, an optional output schema, and a handler function. Toolshed converts those schemas to JSON Schema automatically and registers the tool in the catalog.

​
Sources

Sources let you bring tools into Toolshed without writing handlers manually. A source points to an OpenAPI spec, a GraphQL endpoint, or an existing MCP server. Toolshed introspects the spec or schema, generates tool definitions, and wires up the invocation logic. You configure sources with defineSource() and assign them a namespace that prefixes all generated tool paths (for example, billing.invoices.list).

​
Tool registry

The tool registry is the central catalog of all tools available in your Toolshed deployment. Every plugin and source you register contributes tool definitions to the catalog. When an agent connects through toolshed serve, the runtime exposes a filtered view of the registry based on the agent’s assigned role.

​
Policy

Policy governs which tools a given agent role can invoke. Roles are defined by a set of glob-style path patterns — for example, github.* grants access to all GitHub tools, while slack.messages.send grants access to exactly one. The policy layer resolves a role’s permitted tools at runtime before any invocation reaches a handler.

​
Elicitation

Elicitation is Toolshed’s implementation of the MCP human-in-the-loop requirement. When a tool is marked destructive: true, your handler calls elicit() before performing any irreversible operation. This suspends execution and sends a structured approval request to the user. The handler receives an accept, decline, or cancel response and acts accordingly. Toolshed never auto-proceeds on decline or cancel.

​
Execution runtimes

The toolshed serve command supports two execution backends, controlled by the TOOLSHED_RUNTIME environment variable. The local runtime executes tool handlers in the same process as the MCP server, which is suitable for development and trusted environments. The vercel runtime routes executions to Vercel Firecracker microVMs for full sandboxed isolation — appropriate for production deployments where agent scripts should have no access to the host environment.