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

# MCP Server

> Install the BossMode MCP server into Claude Desktop, Claude Code, Cursor, or Continue — and get all 27 BossMode tools available to your AI agent in seconds.

# MCP Server

`@bossmode/mcp-server` is a stdio [Model Context Protocol](https://modelcontextprotocol.io) server. It exposes BossMode's full surface — directives, approvals, reports, packs, devices, AvatarCzar — as MCP tools. Drop it into any MCP-aware host: Claude Desktop, Claude Code, Continue, Cursor, Zed, and others.

Reach for MCP when an AI agent is the caller and you want it to operate BossMode natively: reading context, queuing directives, and executing approved work without going through the web UI. Every destructive tool returns a `{ status: "pending_approval", approvalId, expiresAt }` envelope — execution happens only when an operator approves via MCP, CLI, TUI, or the web workspace.

## Install in Claude Desktop

Add the following to your `claude_desktop_config.json` (usually at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json theme={null}
{
  "mcpServers": {
    "bossmode": {
      "command": "npx",
      "args": ["@bossmode/mcp-server@latest"],
      "env": {
        "BOSSMODE_TOKEN": "your-token-here"
      }
    }
  }
}
```

## Install in Claude Code

```bash theme={null}
claude mcp add bossmode npx @bossmode/mcp-server@latest
```

Then set your token:

```bash theme={null}
claude mcp set-env bossmode BOSSMODE_TOKEN=your-token-here
```

## Install in Cursor

Open **Cursor Settings → MCP** and add:

```json theme={null}
{
  "mcpServers": {
    "bossmode": {
      "command": "npx",
      "args": ["@bossmode/mcp-server@latest"],
      "env": {
        "BOSSMODE_TOKEN": "your-token-here"
      }
    }
  }
}
```

## Install in Continue

In your `~/.continue/config.json`:

```json theme={null}
{
  "mcpServers": [
    {
      "name": "bossmode",
      "command": "npx",
      "args": ["@bossmode/mcp-server@latest"],
      "env": {
        "BOSSMODE_TOKEN": "your-token-here"
      }
    }
  ]
}
```

## Environment variables

| Variable                 | Required | Description                                                          |
| ------------------------ | -------- | -------------------------------------------------------------------- |
| `BOSSMODE_TOKEN`         | Yes      | Your Pro API token from the BossMode workspace settings              |
| `BOSSMODE_API_URL`       | No       | Override the BossMode API base URL (default: `https://bossmode.ing`) |
| `BOSSMODE_LOCAL_DB_PATH` | No       | Override the local SQLite brain DB path                              |
| `BOSSMODE_MCP_TELEMETRY` | No       | Set to `1` to emit latency logs to stderr for each tool call         |

## Tool catalog

The following 27 tools are sourced directly from `packages/bossmode-mcp-server/src/tools.ts`.

### Context & read tools

| Tool                             | Description                                                                                                                                                         |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bossmode:get-context`           | Pull the full consigliere brief in one call — signals, work packets, standing orders, metrics, audit feed, guardian state, and AvatarCzar persona. Call this first. |
| `bossmode:get-signals`           | Read the latest intelligence from the BossMode signal pipeline.                                                                                                     |
| `bossmode:get-work-packets`      | Retrieve the active work packets — the specific moves the engines have queued for the family to execute.                                                            |
| `bossmode:get-skill-pack`        | Pull a specific SOP from the BossMode skill library (CEO brief, Marketing capo brief, etc.).                                                                        |
| `bossmode:get-consigliere-skill` | Pull the full consigliere SOP — the standing orders that define how the family runs while the boss is away.                                                         |
| `bossmode:get-profile`           | Read the boss's BossMode operator profile — autonomy settings, connected engines, account tier, and consigliere configuration.                                      |
| `bossmode:get-metrics`           | Pull BossMode revenue and performance metrics.                                                                                                                      |
| `bossmode:standing-orders:get`   | Read the standing orders the boss left before stepping out.                                                                                                         |
| `bossmode:get-audit-feed`        | Read the consigliere's action log — every move made, every issue touched, every order executed.                                                                     |

### Pack lifecycle tools

| Tool                           | Description                                                        |
| ------------------------------ | ------------------------------------------------------------------ |
| `bossmode:packs:list`          | List available and installed BossMode packs.                       |
| `bossmode:packs:install`       | Request installation of a BossMode pack. Returns pending approval. |
| `bossmode:packs:activate-slot` | Request activation of a pack slot with OCC-safe approval.          |
| `bossmode:packs:pause`         | Request pausing a running pack. Returns pending approval.          |
| `bossmode:packs:resume`        | Request resuming a paused pack. Returns pending approval.          |

### Device tools

| Tool                      | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `bossmode:devices:list`   | List BossMode devices known to the workspace profile.             |
| `bossmode:devices:pair`   | Request a one-time device pairing code. Returns pending approval. |
| `bossmode:devices:revoke` | Request device revocation. Returns pending approval.              |

### Work & revenue tools

| Tool                     | Description                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------------- |
| `bossmode:work-packet`   | Pull pending work for an MCP-hosted family member. Fetch, acknowledge, execute, post result. |
| `bossmode:track-revenue` | Log a revenue event to the BossMode ledger. Requires boss confirmation before calling.       |
| `bossmode:ack`           | Acknowledge a BossMode signal after acting on it. Requires boss confirmation before calling. |

### Directive & approval tools

| Tool                              | Description                                                                                                 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `bossmode:directive:create`       | Persist a boss directive. Becomes the provenance root for all subsequent comments, actions, and audit rows. |
| `bossmode:directive:list`         | List the boss's directives, filterable by status.                                                           |
| `bossmode:directive:submit`       | Submit a boss directive into the local operator approval queue. Returns pending approval.                   |
| `bossmode:directive:approve`      | Approve and execute a previously queued operator approval.                                                  |
| `bossmode:directive:reject`       | Reject a pending operator approval.                                                                         |
| `bossmode:directive:list-pending` | List pending local operator approvals waiting for the boss.                                                 |

### Report & packet tools

| Tool                    | Description                                                |
| ----------------------- | ---------------------------------------------------------- |
| `bossmode:report:read`  | Read today's or this week's local operator receipt report. |
| `bossmode:packets:list` | List local work packets visible to the operator.           |
| `bossmode:packet:get`   | Get a single local work packet by id.                      |

### Family tools

| Tool                    | Description                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| `bossmode:family:spawn` | Register the six fixed BossMode family roles in the local SQLite brain for OpenClaw, Claude Code, or Hermes. |
| `bossmode:family:list`  | List the locally registered BossMode family members for a customer.                                          |
| `bossmode:family:send`  | Send one assignment to a locally registered family member.                                                   |
| `bossmode:family:close` | Close or pause a locally registered family member without deleting the record.                               |
| `family:issue:comment`  | Post a comment to a work packet thread. The communication backbone for the family.                           |

### Guardian tools

| Tool                        | Description                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| `bossmode:guardian:kill`    | Request the local Guardian kill switch. Requires `confirm=CONFIRM_KILL` and queues a pending approval. |
| `bossmode:guardian:restore` | Request kill-switch restore. Queued for operator approval before state changes.                        |

## First call — a three-step walkthrough

Once the MCP server is wired into your host, the canonical flow an agent runs is:

1. **Read the brief.** Call `bossmode:get-context` first. It returns the full consigliere brief in one round-trip: signals, active work packets, standing orders, the revenue ledger, audit feed, guardian state, and persona. Every other tool flows from what you read here.
2. **Queue a directive.** Call `bossmode:directive:create` with a clear intent in plain language (`"draft the weekly brief for Tuesday and post to #founders"`). You get back `{ directiveId, status: "pending_approval", approvalId }`.
3. **Approve and execute.** Call `bossmode:directive:approve` with the `approvalId`. The operator layer executes the directive, writes a work packet, and the next `bossmode:get-context` will show the packet + the execution audit row.

Destructive tools (`bossmode:guardian:kill`, `bossmode:packs:install`, etc.) use the same approval envelope. If you're building an agent that should be able to act autonomously within a budget, pair the MCP tools with a standing order that pre-approves the scope.

## Token scope + rotation

MCP tokens are workspace-scoped. They authenticate the agent to the workspace they're bound to; they don't grant cross-workspace access. Rotate from Settings → API Keys — old tokens invalidate immediately.

## Troubleshooting

* **`BOSSMODE_TOKEN is not set`** — env var missing. See each host section above for where to set it.
* **`Invalid token`** — your token was rotated. Regenerate from Settings → API Keys.
* **Tool call hangs** — your host may not accept stdio. Check host-specific MCP debug logs. Set `BOSSMODE_MCP_TELEMETRY=1` to get per-tool latency on stderr.