Installation

The Toado MCP server is hosted at:

https://mcp.toado.dev/mcp

Almost every modern client supports OAuth, which means no token to copy or paste. Below are the per-client instructions; if your client is not listed, see the client picker.

OAuth consent screen

On first connect, you will see Toado’s consent screen with three access levels you can pick: Read-only, Read + comment, or Full access. Pick the narrowest one that fits the use case; you can re-authorize at any time to widen or narrow.

Pick your client

Claude Code

Two steps: register the server with the CLI, then authenticate from inside a Claude Code session. The consent screen with the three access levels appears at step 2.

1. Register the server. In your terminal: bash, zsh, PowerShell, or cmd all work. The --scope user flag makes Toado available across all your projects, not just the one you’re in.

claude mcp add toado --transport http https://mcp.toado.dev/mcp --scope user

2. Authenticate. Open a Claude Code session and run /mcp. A browser tab opens for OAuth approval; pick your access level and approve. The token is stored automatically.

• VS Code or Cursor: open the Claude Code chat panel and type /mcp.
• Terminal: run claude in any directory, then type /mcp at the prompt.

Verify with:

claude mcp list

You should see toado in the output.

Prefer a token? Generate one in the token section below and run this instead: it skips the /mcp auth step:

claude mcp add toado --transport http https://mcp.toado.dev/mcp --header "Authorization: Bearer <your-token>" --scope user

Claude Desktop

Claude Desktop has native support for remote MCP servers. OAuth is handled by the app on first connect.

1. Open Claude Desktop › Settings › Connectors.
2. Click Add custom connector.
3. Paste the URL below and click Add. A browser tab opens for OAuth approval.

https://mcp.toado.dev/mcp

See Anthropic’s custom connector guide for screenshots.

Older Claude Desktop versions

Older versions used a JSON config plus the mcp-remote bridge. That is no longer needed if your app is current. Update Claude Desktop, then use the Settings › Connectors flow above.

Cursor

Cursor supports remote MCP servers with OAuth (dynamic registration), so no token is needed.

1. Open Cursor Settings › MCP.
2. Click Add new MCP server, paste the URL below, set the type to http, and save.
3. Approve in the browser tab Cursor opens for OAuth.

https://mcp.toado.dev/mcp

Prefer to edit a config file? Add this to ~/.cursor/mcp.json (or per-project .cursor/mcp.json):

{
  "mcpServers": {
    "toado": {
      "url": "https://mcp.toado.dev/mcp"
    }
  }
}

Codex

OpenAI’s Codex CLI supports OAuth for remote MCP servers. Two steps: add the server to your config, then run the login command.

1. Add this block to ~/.codex/config.toml (or project-scoped .codex/config.toml):

[mcp_servers.toado]
url = "https://mcp.toado.dev/mcp"

2. Run the OAuth login command:

codex mcp login toado

Prefer a token? Use http_headers = { Authorization = "Bearer <token>" } in the TOML block (and skip the codex mcp login step). To keep the token out of the file, use bearer_token_env_var = "TOADO_TOKEN" and set TOADO_TOKEN in your shell.

Other

Any MCP client with HTTP transport plus custom auth headers can connect. This covers Cline, Continue, Goose, Zed, and anything you build with the MCP SDK.

Generate a token, then point your client at:

https://mcp.toado.dev/mcp

With this header on every request:

Authorization: Bearer <your-token>

Examples:

• Cline: Settings › MCP Servers › Add Remote (HTTP).
• Continue: edit ~/.continue/config.yaml (or workspace equivalent) and add an mcpServers entry with the URL and headers above.
• Goose, Zed, custom SDK clients: same pattern, HTTP transport with the bearer header.

Run from source

The server is open source, so you can run it on your own machine instead of connecting to the hosted endpoint. It still talks to the Toado API; only the MCP process is local. Useful for hacking on the server, pointing at a staging backend, or keeping your token out of every client config.

1. Clone and build:

git clone https://github.com/toado-dev/toado-mcp.git
cd toado-mcp
pnpm install
pnpm build

2. Start it, pointing at the API you want it to talk to. The server is HTTP and stateless: it holds no token of its own, and authenticates each request with the bearer that request carries.

VD_API_BASE_URL=https://app.toado.dev/api/v1 \
VD_API_PUBLIC_URL=https://app.toado.dev \
PORT=3002 \
node dist/index.js

3. Register your local server the same way you would the hosted one:

claude mcp add toado --transport http http://localhost:3002/mcp --scope user

Then run /mcp in a Claude Code session to authorize. Verify with claude mcp list. Point VD_API_BASE_URL at a staging or self-hosted backend to work against it; the full environment variable table is in Source and self-hosting.

Verify the connection

In your client, ask:

List my Toado companies.

The client should call list_companies and return your company list. If it does not, see Troubleshooting.

Manual token (alternative)

OAuth covers almost every case. Reach for a manually-issued token only if one of these applies:

• Your client does not support OAuth (Cline, Continue, Goose, Zed, custom SDK builds).
• You are wiring Toado into CI or another non-interactive context where a browser-based OAuth flow does not fit.
• You need a token scoped down to specific companies or projects, or restricted to read-only.
• You are running a self-hosted Toado backend.

Create a token

In the Toado web app, Company settings > MCP tokens:

Tokens are created in the web app under Company settings › MCP tokens › Create token. Pick a label, choose scopes, and optionally restrict to specific companies or projects. The token string is shown once at creation time and cannot be retrieved later, so save it immediately.

Label claude-code on my-laptop Human-readable name. Shows up on every comment and edit the token makes.

Scopes mcp.read mcp.comments mcp.tickets.write mcp.tickets.assign Granular. Read-only audit tokens want just mcp.read. Choose mutation scopes as needed. Jira sending requires a separate explicit mcp.jira.send grant.

Company filter All companies (no filter) Restrict to one company id to scope down a token.

Project filter All projects in those companies Restrict further to specific projects.

Tokens begin with vd_live_ or vd_test_. Treat them like passwords. Revoke at any time from the same settings page; revocation is effective immediately.

1. Click Create token.
2. Label it specifically, e.g. cline on macbook or ci-pipeline. The label shows up on every comment and edit the token makes, so make it scannable.
3. Choose scopes. For a full-power agent, pick all four: mcp.read, mcp.comments, mcp.tickets.write, mcp.tickets.assign. For read-only audits, just mcp.read.
4. Optionally restrict to one company or project.
5. Click Create token. The token appears once. Copy it now: vd_live_example. You cannot retrieve it again.

See Tokens & scopes for the full scope matrix.

Use the token

In any of the per-client instructions above, replace the OAuth path with the bearer-header path. The URL stays the same: https://mcp.toado.dev/mcp. The header is always:

Authorization: Bearer <your-token>

Self-hosted Toado backend

If you are pointing at a self-hosted or staging deployment, swap the host in the URL. Example: https://toado.staging.example.com/mcp. The path (/mcp) and the auth model are identical.

Updating

Hosted Toado MCP is rolled forward server-side; clients reconnect automatically. There is nothing to update on your end.

Where to next

• Quickstart, the five-minute tour from connect to first fix.
• Tokens & scopes, the auth model in depth.
• Tools reference, the full surface of 34 MCP tools.
• Troubleshooting, if the server will not connect.