Toolshed ships as two separate packages: the CLI (@toolshed/cli) that you install globally to get the toolshed command, and the SDK (@toolshed/sdk) that you add as a dependency to the project where you define plugins and tools. This page covers prerequisites, both install paths, environment variable configuration, and how to verify the setup.
Prerequisites
Before installing, make sure your environment meets these requirements:
- Node.js 18 or later — Toolshed uses native ES modules and top-level
await. Check your version with node --version.
- npm, pnpm, or yarn — any of the three package managers work for both the global CLI install and the project SDK install.
The Toolshed monorepo itself uses pnpm internally, but your own project can use whichever package manager you prefer.
Install the CLI
Install @toolshed/cli globally to make the toolshed binary available in your shell:
npm install -g @toolshed/cli
toolshed. After installation, the following commands are available:
| Command | Description |
|---|
toolshed login | Authenticate with your Toolshed server and store a session token |
toolshed serve | Start the MCP stdio server for agent connections |
toolshed run <script> | Execute a TypeScript script in the configured runtime |
Install the SDK
Add @toolshed/sdk as a dependency in the project where you author plugins and tools:
npm install @toolshed/sdk
import {
definePlugin, // Define a plugin with tools and auth providers
defineTool, // Define a single tool with type-safe schema and handler
defineSource, // Define a tool source (OpenAPI, GraphQL, MCP, or plugin)
elicit, // Request human approval mid-tool-execution
} from "@toolshed/sdk"
Environment variables
Both the CLI and SDK read configuration from environment variables. Set these before running toolshed serve or toolshed run.
| Variable | Default | Description |
|---|
TOOLSHED_SERVER | http://localhost:3000 | URL of the Toolshed server. Points the CLI at a remote server for login, tool catalog fetching, and policy resolution. |
TOOLSHED_RUNTIME | local | Execution backend for tool handlers. Set to local for in-process execution or vercel to route executions through Vercel Firecracker microVMs. |
Vercel runtime variables
When TOOLSHED_RUNTIME=vercel, the following additional variables are required:
| Variable | Description |
|---|
VERCEL_TEAM_ID | Your Vercel team ID |
VERCEL_PROJECT_ID | The Vercel project to deploy execution snapshots to |
VERCEL_TOKEN | A Vercel API token with deployment permissions |
TOOLSHED_SNAPSHOT_ID | (Optional) A specific snapshot ID to use for executions |
Never commit VERCEL_TOKEN or other secrets to version control. Read them from a .env file that is listed in .gitignore, or inject them from your CI/CD secret store at runtime.
Verify the installation
Confirm the CLI is installed and on your PATH:
You should see the current version number printed to stdout, for example 0.0.1. If the command is not found, check that your global node_modules/.bin directory is on your PATH.
On some systems, globally installed npm packages are not automatically on PATH. Run npm bin -g (or pnpm bin -g) to find the directory, then add it to your shell profile if needed.