> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# toolshed serve

> Start an MCP server over stdio for agent connections.

## Usage

```bash theme={null}
toolshed serve
```

Starts an MCP server that communicates over stdio, allowing MCP clients like Claude or Cursor to connect.

## Prerequisites

You must be logged in first. Run [`toolshed login`](/cli/login) if you haven't already. The command will exit with an error if no config is found.

## How it works

1. Loads credentials from `~/.toolshed/config.json`
2. Fetches the tool catalog from `GET /api/registry` using the session token
3. Creates a runtime (local or Vercel sandbox) with the user's role and tool set
4. Starts the MCP server on stdio transport
5. When an agent calls a tool, the CLI vends a token from `POST /api/tokens/vend` and executes the tool handler

## Connecting from Claude

Add Toolshed to Claude's MCP server config:

```json theme={null}
{
  "mcpServers": {
    "toolshed": {
      "command": "node",
      "args": ["<path-to-repo>/apps/cli/dist/index.js", "serve"]
    }
  }
}
```

Claude spawns the process, connects over stdin/stdout, and discovers tools via MCP's `tools/list`.

## Environment variables

| Variable            | Default | Description                             |
| ------------------- | ------- | --------------------------------------- |
| `TOOLSHED_RUNTIME`  | `local` | Runtime backend: `local` or `vercel`    |
| `VERCEL_TEAM_ID`    | —       | Required when `TOOLSHED_RUNTIME=vercel` |
| `VERCEL_PROJECT_ID` | —       | Required when `TOOLSHED_RUNTIME=vercel` |
| `VERCEL_TOKEN`      | —       | Required when `TOOLSHED_RUNTIME=vercel` |

## Authentication flow

When an agent calls a tool that requires OAuth credentials (e.g., `github.issues.create`):

1. The CLI looks up the tool's `authProvider` field
2. Calls `POST /api/tokens/vend` with the user's ID and provider name
3. The server decrypts the stored OAuth token (refreshing if expired)
4. The CLI receives a usable access token and passes it to the tool handler

Tokens are vended per-call — they never persist on disk or in the MCP transport.