# FlockTab MCP server

FlockTab puts a spend cap and a kill switch on every AI agent. The MCP server lets any agent read spend and act on a flock: list tabs, close or reopen an Agent, change a cap, record and attribute outside spend.

Server URL: https://console.flocktab.com/api/mcp

Transport: Streamable HTTP. Auth: OAuth 2.1 (discovered from the URL; a person approves in the FlockTab console).

## Set up

### Claude Code

Add the server, then run /mcp inside Claude Code, pick flocktab and Authenticate.

```
claude mcp add --transport http flocktab https://console.flocktab.com/api/mcp
```

### Codex

Add the server, then sign in once; the browser opens the console.

```
codex mcp add flocktab --url https://console.flocktab.com/api/mcp
codex mcp login flocktab
```

### Cursor

In .cursor/mcp.json (or ~/.cursor/mcp.json for every project). Cursor asks you to connect the first time.

```
{
  "mcpServers": {
    "flocktab": { "url": "https://console.flocktab.com/api/mcp" }
  }
}
```

### claude.ai and Claude Desktop

Settings, Connectors, Add custom connector. Paste the URL and connect.

```
https://console.flocktab.com/api/mcp
```

### Any other MCP client

Streamable HTTP with OAuth. Point it at the URL; it discovers the rest.

```
https://console.flocktab.com/api/mcp
```

## Access

- The agent acts as the person who approved it, in the flock they chose, with their role's permissions. Project-limited roles stay limited.
- Permissions are checked again on every call, so a role change or suspension applies at once.
- Nothing to paste: OAuth 2.1 with PKCE and dynamic client registration, like Resend's and Cloudflare's MCP servers. The console's sign-in, passkey and SSO rules apply to the approval.
- Access tokens last an hour and refresh themselves for 30 days. Account, Security, Connected apps lists every connection; Disconnect revokes it at once.

## Tools

| Tool | What it does | Needs |
|---|---|---|
| `whoami` | The person and flock this connection acts for, and what their role allows. | signed in |
| `list_tabs` | Every Agent's tab: open or closed, cap, spend this window, project. | spend:read |
| `get_spend` | Spend for month, 7d, 30d or 90d: metered, outside, subscription use, by project, Agent and day. | spend:read |
| `list_decisions` | Ledger rows, newest first: each call the proxy allowed or refused, with its amount and reason, and total, every row in the ledger. For older rows pass next_before back as before; it pages to the first row without repeating one. | spend:read |
| `list_guard_holds` | What Agent Guard held for a person and what people decided, as the Agent Guard page shows it: Waiting, Blocked, Allowed or All, each tab's count (all time), newest first with older pages by cursor; and this month's Agent Guard judgments against the plan's cap with its reset in the flock's time. Read only: it cannot allow or refuse a call. Team and Fleet. | spend:read |
| `close_tab` | Stop one Agent. Its next call is denied before the provider. | tabs:write |
| `reopen_tab` | Let a closed Agent spend again. | tabs:write |
| `set_tab_cap` | Change an Agent's cap, in dollars. | tabs:write |
| `close_all_tabs` | The kill switch: close every tab in the flock, including any its cap would reopen at the next window. Returns how many it closed. | tabs:write, whole flock |
| `open_all_tabs` | Reopen every closed tab in the flock, except one set to close for good at its cap. Returns how many it reopened. | tabs:write, whole flock |
| `list_outside_spend` | Bills that never went through the tab (synced vendors and bills recorded by hand), for a range, one day or one vendor: that set's total and per-project totals, the largest lines (up to 500), and how many smaller lines were left out. A line split across projects reads project "shared" and lists each project's part; a $0 line inside a vendor allowance shows its usage. | outside:read |
| `record_outside_spend` | Add spend that bypassed the tab (an invoice, a contract, a card charge). Team and Fleet. | outside:write |
| `attribute_outside_spend` | Give outside spend to a project, share it by Agent activity, or clear it. | outside:write, whole flock |

## Notes

- Money is dollars as strings with cents, for example "12.34".
- Tools name Agents by slug, as list_tabs returns them.
- A tool the role does not allow answers with an error saying so. Do not retry it; ask the person.

Human-readable version: https://flocktab.com/docs/mcp
