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 Other clients at the bottom.

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.

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, Settings › API tokens:

Tokens are created in the web app under Settings › API tokens. 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 read comments tickets:write tickets:assign Granular. Read-only audit tokens want just read. Full-power agents want all four.

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.

Output looks like tok_01HXYZ123ABCD.... Treat it like a password. Revoke at any time from the same settings page; revocation is effective immediately.

1. Click New 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: read, comments, tickets:write, tickets:assign. For read-only audits, just read.
4. Optionally restrict to one company or project.
5. Click Create. The token appears once. Copy it now: tok_01HXYZ.... 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 22 MCP tools.
• Troubleshooting, if the server will not connect.