Get started

Connect an agent

Each agent works with its own access token, and every change it makes is recorded under that token’s name, so you can tell agents apart and revoke one without touching the others. There are two ways to give an agent a token: sign in from the agent (OAuth), or create one yourself and paste it into the agent’s config.

On this page

Web chat apps such as claude.ai and ChatGPT take only a URL for a custom connector, then send you to sign in. Claude Code does the same when you add the server without a token. This needs the server’s ROADMAP_BASE_URL set (see Deployment).

claude.ai: open Settings → Connectors → Add custom connector, and give it your server’s /mcp address, such as https://roadmap.example.com/mcp.

Claude Code:

terminal

claude mcp add --transport http roadmap https://roadmap.example.com/mcp

Then run /mcp in Claude Code and choose Authenticate.

Either way, a browser tab opens on your Roadmap server. Sign in if you aren’t, and you see a page naming the app and where it sends you back to. Tick Read only if the app should only look, then click Allow.

The connection appears in Settings → Access tokens as a connected app, under the app’s name. Revoking it there disconnects the app. Its access token lasts an hour and the app renews it on its own; if it goes unused for 30 days, you sign in again.

The rest of this page is the other way: a token you create and paste.

1. Create a token#

In the web UI, open Settings → Access tokens and create one token per agent. Tick read-only for an agent that should only look (a dashboard, a CI report): it can call every read, and every write is refused.

The token starts with rmp_ and is shown once. Below, replace rmp_... with it and https://roadmap.example.com with your server’s address (http://127.0.0.1:8080 for a local run).

2. Point the agent at `/mcp`#

The server speaks MCP over streamable HTTP at /mcp. The Connect an agent dialog in the web UI’s help menu shows the same config with your server’s address filled in.

Claude Code#

terminal
claude mcp add --transport http roadmap https://roadmap.example.com/mcp \
  --header "Authorization: Bearer rmp_..."

Add --scope project to write it to the repository’s .mcp.json instead of your user config. Don’t commit a real token.

Cursor, and other clients that take an `mcpServers` URL#

.cursor/mcp.json in a project, or ~/.cursor/mcp.json for every project:

json
{
  "mcpServers": {
    "roadmap": {
      "url": "https://roadmap.example.com/mcp",
      "headers": { "Authorization": "Bearer rmp_..." }
    }
  }
}

Claude Desktop, and other clients that only speak stdio#

These clients start a local command and talk to it over stdin and stdout. The roadmap binary has a stdio mode for this: it proxies to your server and never opens a database. Get the binary from the releases page or with go install github.com/emb715/roadmap/cmd/roadmap@latest.

json
{
  "mcpServers": {
    "roadmap": {
      "command": "roadmap",
      "args": ["mcp", "--stdio", "--addr", "https://roadmap.example.com"],
      "env": { "ROADMAP_TOKEN": "rmp_..." }
    }
  }
}

--addr takes an https:// URL for a server behind TLS, or a bare host:port such as 127.0.0.1:8080 for a local one over plain HTTP.

For Claude Desktop this goes in claude_desktop_config.json (Settings → Developer → Edit Config). Restart the app afterwards. If roadmap is not on the app’s PATH, give command the binary’s full path.

3. Let it work#

Ask the agent what it can see, for example “list the open issues in Roadmap”. When it moves an issue to In review, the issue lands in the Review inbox, where a person approves it. Agents can propose changes to documents but never approve them.

Scripts and CI: the REST API#

Anything that is not an MCP client can use the same token against /api/v1:

terminal
export ROADMAP=https://roadmap.example.com
export ROADMAP_TOKEN=rmp_...
curl -H "Authorization: Bearer $ROADMAP_TOKEN" $ROADMAP/api/v1/projects

Every MCP tool has one endpoint. The OpenAPI document is served at /api/v1/openapi.json. See docs/API.md for rate limits, CORS and file uploads.

Troubleshooting#

401 Unauthorized. The token is missing, mistyped or revoked. Check the header is exactly Authorization: Bearer rmp_....
The app says the server doesn’t support sign-in. The server has no ROADMAP_BASE_URL, or an operator set ROADMAP_OAUTH=off. Use a token you create instead.
“This sign-in link does not work.” The app’s registration expired or the link was changed. Start connecting again from the app.
403 on a write. The token is read-only.
The agent sees no tools. Make sure the URL ends in /mcp, and that the server is reachable from where the agent runs (a local server binds 127.0.0.1 only).

Sign in from the agent#