Install the Tempo MCP

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	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	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

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.)

2. Add the server to your client

Claude Code
Codex CLI
Cursor
Any other agent

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:

{
  "mcpServers": {
    "tempo": { "command": "npx", "args": ["-y", "@tempo-ai/mcp"] }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.tempo]
command = "npx"
args = ["-y", "@tempo-ai/mcp"]

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "tempo": { "command": "npx", "args": ["-y", "@tempo-ai/mcp"] }
  }
}

Any agent or framework that supports stdio MCP servers works — the config is always the same three values:

{ "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.

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:

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:

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:

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).

Claude Code cloud
Codex cloud
Grok Bot / other bot VMs
CI

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:

Environment variable: TEMPO_AUTH_TOKEN=tempo_...
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.

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

Secret / env var: TEMPO_AUTH_TOKEN=tempo_...
Setup script:

npm install -g @tempo-ai/mcp
npx playwright install chromium  # optional — first canvas capture auto-installs it otherwise

Tell the agent the CLI exists. Unlike MCP, a CLI isn’t advertised to the model automatically — add the AGENTS.md snippet to your repo (Codex reads AGENTS.md on every task, local and cloud).

The agent then discovers and calls tools on its own:

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"}'

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:

Clone the repo it should work on.
Install Node 20+, then npm install -g @tempo-ai/mcp.
Persist TEMPO_AUTH_TOKEN=tempo_... in its environment.
Add the AGENTS.md snippet 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.

Store the token as a CI secret, expose it as TEMPO_AUTH_TOKEN, and call any tool from a job step:

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.

Using the CLI instead of MCP

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

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:

## 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.

ChatGPT (web)
claude.ai / Claude mobile
Other remote-MCP clients

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.)
Settings → Plugins → + → name it “Tempo”, paste https://mcp.tempo.new/mcp, authentication OAuth.
Approve the Tempo sign-in consent.
In a chat, enable the Tempo plugin from the plus menu. Write actions ask for confirmation before executing.

Settings → Connectors → Add custom connector.
Paste https://mcp.tempo.new/mcp and complete the OAuth consent.

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.

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.

Getting Started

Features

Guides

Migration Guides

Changelog

Legal

Install the Tempo MCP

Which one do I need?

Install on your machine

2. Add the server to your client

3. That’s it — canvas included

Cloud and headless environments

Using the CLI instead of MCP

Tell the agent the CLI exists

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

How scoping works

Options

Good to know

​Which one do I need?

​Install on your machine

​1. Sign in once

​2. Add the server to your client

​3. That’s it — canvas included

​Cloud and headless environments

​Using the CLI instead of MCP

​Tell the agent the CLI exists

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

​How scoping works

​Options

​Good to know

Which one do I need?

Install on your machine

1. Sign in once

2. Add the server to your client

3. That’s it — canvas included

Cloud and headless environments

Using the CLI instead of MCP

Tell the agent the CLI exists

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

How scoping works

Options

Good to know