MCP server

Gloom Cloud hosts a Model Context Protocol server at https://api.gloom.sh/mcp. It gives an agent the research tools Gloom's own assistant uses, and with the right access your notes, teams and connected brokers. Part of Gloom Pro.

The same keys work for the REST API and Google Sheets. With Terminal control the same server also drives your open desktop or TUI; for one-off reports, use the CLI.

Connect

Sign in from the client. OAuth clients (Claude Code, claude.ai, Cursor and most recent clients) only need the endpoint. The first call opens a browser tab where you choose what the client may reach.

claude mcp add --transport http gloom https://api.gloom.sh/mcp

Use a key. For scripts and clients without a browser, create a key in Cloud settings, Agents and send it as a bearer token (x-api-key also works). Keys are shown once; you can hold up to 10.

claude mcp add --transport http gloom https://api.gloom.sh/mcp \
  --header "Authorization: Bearer gloom_mcp_..."

export GLOOM_MCP_KEY=gloom_mcp_...
codex mcp add gloom --url https://api.gloom.sh/mcp --bearer-token-env-var GLOOM_MCP_KEY

{
  "mcpServers": {
    "gloom": {
      "url": "https://api.gloom.sh/mcp",
      "headers": { "Authorization": "Bearer gloom_mcp_..." }
    }
  }
}

Raw HTTP is stateless: one JSON reply per POST, and GET and DELETE return 405.

Access

A key's access, Terminal control and optional team pin are fixed at creation. Signed-in clients get the same levels through the mcp:read, mcp:write and mcp:terminal scopes; the consent page leaves Terminal control unticked. tools/list returns only what the caller may call.

Tools

Read-only unless marked write. Most take limit; ? marks an optional argument. tools/list has the full schema. Start with market.search when a ticker is ambiguous.

Market

Company

Filings and ownership

Macro and news

Events and credit

Company data

Markets and compute

Supply chain and power

Notes and teams

notes.save replaces the whole note, so read it first and pass expectedRevision; a newer edit returns revision_conflict. quantity applies to portfolios only.

Portfolio

Brokers

Connect a broker in Gloom and every client with read access reaches it through Gloom. The portfolio.* tools cover every connected broker in one call and need no Pro.

With no connection they return no rows and a note; a broker that fails adds an error row and the result is partial. They read brokerage accounts, not team portfolios (use collections.get).

An IBKR order instruction is not an order: IBKR returns a link where you review and submit it yourself.

Terminal control

Terminal control reaches everything the remote API does in your open, signed-in desktop or TUI: read the screen, open and arrange panes, navigate tickers, switch and edit layouts, semantic UI actions and plugin capabilities. The app asks once before an assistant takes over; plugin capabilities, button presses, commands and anything that reaches an outside service (orders, transfers, messages) ask you in the app on every call, and an unanswered one is denied after 60 seconds.

Claude Code ──MCP──> api.gloom.sh/mcp ──Cloud socket──> your Gloom app ──> panes, layouts, tickers
                                                             │
                                          asks you: once per assistant, every call that leaves the app

Each tool takes device? (an id or name from terminal.devices). Descriptions carry the operation's tier and whether you confirm each call. A call that waits on you longer than 45 seconds answers pending with a callId; read the outcome with terminal.call_result. With no app open, tools answer no_terminal. Revoke an assistant in the app (Account Management, Agents), or revoke its key or disconnect it here, and its next call stops.

Results and limits

Each call returns text plus structuredContent with status (ok, partial when a limit removed rows, or error), rowCount, truncated, asOf and data. Results are capped at 256 KB. A failed source returns status: "error" with data.error = { code, source, reason }. terminal.pane.screenshot returns the same JSON as text plus an image block, and no structuredContent, since some clients read only that and would drop the image.

Creating keys needs Pro. Any valid key can initialize and tools/list; tool calls need Pro, except portfolio.*, and get real-time quotes and the live news wire.

Keys allow 120 requests a minute and 5,000 a day; over the limit returns 429 with Retry-After. If Pro lapses, keys stay but tool calls are refused. Revoking a key applies on the next request; a disconnected client's token expires within two hours, and its terminal calls stop at once.