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

# Install the Tempo MCP

> Use Tempo's issues, docs, Slack, Linear, and canvas tools from Claude Code, Codex, Cursor, cloud agents, any terminal — or from ChatGPT and claude.ai on the web

Tempo's tools are available **outside** the Tempo app in two forms. They
expose the same tools with the same explicit scoping — pick by **where your
AI runs**, and never set up both in the same client.

## Which one do I need?

| Where your AI runs                                                                                                            | Install this                                                                                                                | What you get                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A coding agent or terminal on a machine** — Claude Code, Codex CLI, Cursor, cloud agent sandboxes, CI                       | 📦 The npm package `@tempo-ai/mcp` — [jump to setup](#install-on-your-machine)                                              | The FULL suite: issues, docs, comments, agents, run scripts, Slack, Linear — reads and writes — plus canvas tools (screenshots, share links) inside a Tempo repo |
| **A chat app in the browser or on your phone** — ChatGPT, claude.ai, Claude mobile, or any client that takes a remote MCP URL | 🌐 The hosted server `https://mcp.tempo.new/mcp` — [jump to setup](#connect-from-chatgpt-claude-ai-or-mobile-hosted-server) | Issues, docs, comments, agents, scripts, Slack, Linear — reads and writes. No canvas tools (there's no filesystem behind a URL)                                  |

Rule of thumb: **if the client can run a command, use the npm package. If
all you can give it is a URL, use the hosted server.**

***

`@tempo-ai/mcp` brings Tempo's full tool surface to AI agents: issues, docs,
canvas comments, custom agents, run scripts, Slack (as your org's Tempo
bot), Linear, and — inside a Tempo-enabled repo — the canvas tools,
including **screenshots and share links with real previews** rendered from
your production components.

It works two ways, always with the same tools and the same explicit scoping:

* **As an MCP server** — for hosts that attach stdio MCP servers (Claude
  Code, Codex CLI, Cursor, Claude Code cloud sessions).
* **As a CLI** — `tempo-mcp tools` / `tempo-mcp call` — for environments
  with a terminal but no MCP support (Codex cloud, Grok Bot, CI jobs).

You don't need the Tempo app installed on the machine. You just need a Tempo
account and Node.js 20+.

## Install on your machine

### 1. Sign in once

```bash theme={null}
npx -y @tempo-ai/mcp login
```

This opens your browser to sign in to Tempo. Credentials are stored locally
per machine. (For machines without a browser, see
[Cloud and headless environments](#cloud-and-headless-environments).)

### 2. Add the server to your client

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add tempo -- npx -y @tempo-ai/mcp
    ```

    Run it inside a project folder to scope the server to that project, or add
    `--scope user` to enable it everywhere. To share it with your whole team
    (and with Claude Code **cloud sessions**), commit a `.mcp.json` at the
    repo root instead:

    ```json theme={null}
    {
      "mcpServers": {
        "tempo": { "command": "npx", "args": ["-y", "@tempo-ai/mcp"] }
      }
    }
    ```
  </Tab>

  <Tab title="Codex CLI">
    Add to `~/.codex/config.toml`:

    ```toml theme={null}
    [mcp_servers.tempo]
    command = "npx"
    args = ["-y", "@tempo-ai/mcp"]
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for
    all projects):

    ```json theme={null}
    {
      "mcpServers": {
        "tempo": { "command": "npx", "args": ["-y", "@tempo-ai/mcp"] }
      }
    }
    ```
  </Tab>

  <Tab title="Any other agent">
    Any agent or framework that supports **stdio MCP servers** works — the
    config is always the same three values:

    ```json theme={null}
    { "command": "npx", "args": ["-y", "@tempo-ai/mcp"] }
    ```

    If your agent has a terminal but no MCP support, skip the server
    entirely and use the CLI: see
    [Using the CLI instead of MCP](#using-the-cli-instead-of-mcp).
  </Tab>
</Tabs>

### 3. That's it — canvas included

Canvas tools appear automatically when the agent runs inside a repo that has
Tempo canvases (a `tempo/tempo.config.json`). Screenshots and share links
render headlessly with Chromium, which **downloads itself automatically on
the first capture** (one-time, \~2 min; cached per machine afterwards). To
make that first capture instant, you can pre-install it:

```bash theme={null}
npx playwright install chromium
```

Share links additionally require the canvas's branch to be committed and
pushed. Locked-down environments can disable the automatic download with
`TEMPO_MCP_NO_AUTO_INSTALL=1` — captures then fail with the manual install
command instead.

Ask your agent to "list my Tempo issues" — or "share my canvas" — to
confirm it works.

## Cloud and headless environments

Cloud agent sandboxes have no browser, so `login` can't run there. Instead,
mint a **personal access token** on your own machine:

```bash theme={null}
npx -y @tempo-ai/mcp token create --name my-cloud-agent
```

The token (`tempo_...`) prints exactly once. Set it in the cloud environment
as `TEMPO_AUTH_TOKEN` — the CLI signs in with it automatically, no browser
involved. Verify from the environment with:

```bash theme={null}
npx -y @tempo-ai/mcp whoami
```

Everything the token's agent does acts as **you**; revoke it anytime with
`npx -y @tempo-ai/mcp token revoke <prefix>` (and list with `token list`).

<Tabs>
  <Tab title="Claude Code cloud">
    Cloud sessions (from claude.ai/code or the desktop app) clone your repo
    into Anthropic's sandbox and launch the repo's `.mcp.json` servers
    inside it — so with the `.mcp.json` above committed, the full tool
    surface (canvas included) works. Configure the **cloud environment**
    once:

    1. **Environment variable**: `TEMPO_AUTH_TOKEN=tempo_...`
    2. **Network access**: add `*.convex.cloud` and `*.convex.site` to the
       allowlist (Custom access), plus `tempo.new` for share links.

    Optional speed-up: `npx playwright install chromium` in the setup
    script (cached across sessions) so the first canvas capture skips the
    automatic Chromium download.
  </Tab>

  <Tab title="Codex cloud">
    Codex cloud has no MCP support, but its container has your repo and a
    terminal — use the CLI. In the environment settings:

    1. **Secret / env var**: `TEMPO_AUTH_TOKEN=tempo_...`
    2. **Setup script**:

    ```bash theme={null}
    npm install -g @tempo-ai/mcp
    npx playwright install chromium  # optional — first canvas capture auto-installs it otherwise
    ```

    3. **Tell the agent the CLI exists.** Unlike MCP, a CLI isn't
       advertised to the model automatically — add the
       [AGENTS.md snippet](#tell-the-agent-the-cli-exists) to your repo
       (Codex reads `AGENTS.md` on every task, local and cloud).

    The agent then discovers and calls tools on its own:

    ```bash theme={null}
    tempo-mcp tools --schemas
    tempo-mcp call issues_list_issues --json '{"orgId": "..."}'
    tempo-mcp call canvas_share --json '{"orgId": "...", "projectId": "...", "canvas": "tempo/designs/my-canvas"}'
    ```
  </Tab>

  <Tab title="Grok Bot / other bot VMs">
    Grok Bot's cloud computer attaches only remote-URL MCP servers, but it
    has a persistent VM with a terminal — same CLI recipe as Codex cloud.
    Tell the bot (once) to:

    1. Clone the repo it should work on.
    2. Install Node 20+, then `npm install -g @tempo-ai/mcp`.
    3. Persist `TEMPO_AUTH_TOKEN=tempo_...` in its environment.
    4. Add the [AGENTS.md snippet](#tell-the-agent-the-cli-exists) to the
       repo (or the bot's standing instructions) so it knows to reach for
       the CLI.

    From then on it uses `tempo-mcp tools` / `tempo-mcp call` for
    everything, canvas share included.
  </Tab>

  <Tab title="CI">
    Store the token as a CI secret, expose it as `TEMPO_AUTH_TOKEN`, and
    call any tool from a job step:

    ```bash theme={null}
    npx -y @tempo-ai/mcp call canvas_share --json "$ARGS_JSON"
    ```

    Chromium auto-installs on the first capture; pre-install it
    (`npx playwright install chromium`) or use an image that ships it to
    keep job time down.
  </Tab>
</Tabs>

## Using the CLI instead of MCP

Every tool the MCP server exposes is also callable directly — same
pipeline, same scoping, no per-tool differences:

```bash theme={null}
tempo-mcp tools                # list every tool
tempo-mcp tools --schemas      # include argument schemas
tempo-mcp call <tool> --json '{"orgId": "...", ...}'
```

`call` prints the tool result to stdout and exits non-zero on tool errors.
`--json -` reads the argument object from stdin. Both commands accept
`--toolsets` and `--readonly`.

### Tell the agent the CLI exists

An MCP host advertises Tempo's tools to the model automatically. A CLI
doesn't — like `gh` or `aws`, the agent only uses it when its instructions
say to. Add this to your repo's `AGENTS.md` (Codex reads it on every task)
or your agent's standing instructions:

```markdown theme={null}
## Tempo

For Tempo issues, docs, comments, agents, Slack, Linear, and canvas
screenshots/share links, use the Tempo CLI:

- `tempo-mcp tools --schemas` — list every tool with its argument schema
- `tempo-mcp call <tool> --json '{...}'` — invoke a tool

Every scoped tool needs an explicit `orgId` (and sometimes `projectId`) —
discover them first with `tempo-mcp call tempo_list_orgs --json '{}'` and
`tempo-mcp call tempo_list_projects --json '{"orgId": "..."}'`.
```

Harmless to keep alongside an MCP setup — hosts with MCP attached will
just use the tools directly.

## Connect from ChatGPT, claude.ai, or mobile (hosted server)

Chat apps on the web can't run `npx` — they connect to Tempo's **hosted MCP
server** instead. One URL for every client:

```
https://mcp.tempo.new/mcp
```

Paste it, complete the Tempo sign-in consent (OAuth), and every call runs
as your Tempo account — reads and writes, with org membership re-verified
server-side on every call. Canvas tools aren't available here (there's no
filesystem behind a URL) — use the npm package in a coding agent for design
work.

<Tabs>
  <Tab title="ChatGPT (web)">
    1. Settings → **Security and login** → enable **Developer mode**.
       (Without it, custom plugins only run search-style deep-research
       tools — Developer mode unlocks full tool calling.
       Business/Enterprise workspaces: an admin must first allow it under
       Workspace Settings → Permissions & Roles → Connected Data.)
    2. Settings → **Plugins** → **+** → name it "Tempo", paste
       `https://mcp.tempo.new/mcp`, authentication **OAuth**.
    3. Approve the Tempo sign-in consent.
    4. In a chat, enable the Tempo plugin from the **plus menu**. Write
       actions ask for confirmation before executing.
  </Tab>

  <Tab title="claude.ai / Claude mobile">
    1. Settings → **Connectors** → **Add custom connector**.
    2. Paste `https://mcp.tempo.new/mcp` and complete the OAuth consent.
  </Tab>

  <Tab title="Other remote-MCP clients">
    Any client that supports **streamable-HTTP MCP servers with OAuth**
    works with the same URL. Coding agents can use it too
    (`claude mcp add --transport http tempo-hosted https://mcp.tempo.new/mcp`),
    but prefer the npm package there — it adds canvas tools.
  </Tab>
</Tabs>

**Connection options** (query params on the URL):

| Param                   | Effect                                                                                               |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| `?readonly=1`           | Strict read-only connection — write tools are never even registered                                  |
| `?toolsets=issues,docs` | Serve only the named toolsets (`issues`, `docs`, `comments`, `agents`, `scripts`, `slack`, `linear`) |

An authorized connector acts as **you** — only connect clients you trust,
or pin them read-only with `?readonly=1`.

## How scoping works

This is identical on both the npm package and the hosted server. Your
sign-in (browser, token, or OAuth consent) provides **identity**; every tool call
carries **explicit scope**. The AI discovers your organization and project
ids with the built-in `tempo_list_orgs` and `tempo_list_projects` tools and
passes them on each call — you never configure an org on the connection, and
membership is re-verified server-side on every call.

## Options

| Flag                     | Effect                                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `--readonly`             | Registers no write tools at all — good for a first session                                                     |
| `--toolsets issues,docs` | Serve only the named toolsets (`issues`, `docs`, `comments`, `agents`, `scripts`, `slack`, `linear`, `canvas`) |

Add flags after the package name, e.g. `npx -y @tempo-ai/mcp --readonly`.

## Good to know

* **Inside the Tempo app you don't need this** — the app provides the same
  tools natively (and skips a user-installed copy to avoid duplicates).
* Writes act as **you** — the signed-in Tempo user — with the same org
  permissions you have in the app. That includes anything a
  `TEMPO_AUTH_TOKEN` holder does, so treat tokens like passwords and revoke
  ones you stop using.
* `npx -y @tempo-ai/mcp logout` clears the stored credentials;
  `npx -y @tempo-ai/mcp whoami` shows who's signed in.