◆ docs

The MCP server

rickub hosts a remote Model Context Protocol server, so an AI agent — Claude Code, Cursor, or anything that speaks MCP — can read and drive your repositories with the same access token you use for the API.

The server lives at https://rickub.com/api/mcp and speaks the remote Streamable HTTP transport (JSON-RPC 2.0 over a single HTTPS endpoint — no local process to install, nothing to keep running on your machine). Point a client at the URL, hand it a token, and it can call rickub's tools directly.

Mint a token

The MCP server authenticates with a personal access token — the same token the JSON API and CLI use, sent as Authorization: Bearer <token>. Create one under Settings → Access tokens, copy it once, and keep it somewhere your client can read it (an environment variable or your client's secret store).

Tip

Give an agent the narrowest token it needs. A Read-only token lets an agent browse code, read issues and watch CI, but every mutating tool refuses it — the safest default for an assistant you only want to look. Hand out a Full access token only when the agent genuinely needs to open merge requests, comment, or dispatch workflows.

Connect Claude Code

Claude Code adds a remote MCP server in one command — the http transport is the Streamable HTTP one, and a header carries your token:

claude mcp add --transport http rickub https://rickub.com/api/mcp \
  --header "Authorization: Bearer $RICKUB_TOKEN"

That writes the server into Claude Code's config; claude mcp list shows it and /mcp inside a session lists the tools it exposes.

Connect any MCP client

Clients that read a JSON config (Cursor, Claude Desktop, and most others) take an mcpServers entry with a url and a bearer header. The shape is the same everywhere:

{
  "mcpServers": {
    "rickub": {
      "url": "https://rickub.com/api/mcp",
      "headers": { "Authorization": "Bearer rickub_pat_xxx" }
    }
  }
}

Note

Different clients keep this file in different places (a project .mcp.json, a global settings file, or a GUI form). Whatever the location, the url + Authorization header pair is all rickub needs — it is a plain remote server with no custom handshake.

Verify it works

Once the server is added, ask your agent to run the list_repos tool (or whoami) — a token that is wired up correctly comes straight back with your repositories. To check the endpoint by hand, list the tools then call a read-only one over plain HTTPS:

# list the tools the server offers
curl -sS https://rickub.com/api/mcp \
  -H "Authorization: Bearer $RICKUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# call one — who owns this token?
curl -sS https://rickub.com/api/mcp \
  -H "Authorization: Bearer $RICKUB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

Heads up

A missing or wrong token gets a 401, never a partial answer — an unreadable repository returns a not-found rather than confirming it exists. If a mutating call comes back this token is read-only, mint a Full-access token for that agent.

What the tools cover

The server exposes more than forty tools, each one backed by the same permission checks and plan limits as the website and the JSON API — so an agent can never do through MCP what its token could not do in the browser. The surface, by area:

Repositories — list_repos, get_repo, create_repo, update_repo, delete_repo, and collaborators via add_collaborator / remove_collaborator.
Merge requests — list_merge_requests, get_merge_request, create_merge_request, comment_merge_request, review_merge_request, merge_merge_request, close_merge_request / reopen_merge_request.
Issues, labels & milestones — list_issues, get_issue, create_issue, update_issue, comment_issue, set_issue_labels, and the *_milestone tools.
CI — list_runs, get_run, get_run_logs, dispatch_workflow, rerun_run, cancel_run, and a server-side wait_for_run that blocks until a run finishes. See CI / Actions to learn what those runs do.
Code browsing — get_file, list_dir, list_commits, get_commit, compare, list_refs.
Organizations & search — get_org, list_org_members, list_org_teams, and search_repos.

The tools return the same JSON shapes as the JSON API, so anything you can read there an agent can read here. Never gonna let a stale token down: revoke it under Settings → Access tokens and every client using it stops at once.

Next steps