# Connect to Claude and other AI assistants

> Use Manage Runners from Claude, Claude Code and other MCP clients through the remote MCP server, with permissions you choose, confirmations for paid changes and a dashboard step for secrets.

Source: https://managerunners.com/docs/manual/connect-to-claude/

Manage Runners is a remote MCP server. It works with Claude, Claude Code and other MCP clients that support Streamable HTTP and MCP authorization. Add it to your AI assistant by its URL, sign in with your Manage Runners account, and choose what the assistant may do. It can then list your runners, caches and metrics connections, read metrics and schedules, and, if you allow it, create, pause, resume, update or delete them. Tokens and other secrets are never typed into the chat: you enter them on a Manage Runners page that the assistant links to. Nothing needs to be installed.

The connector URL is:

```text
https://api.managerunners.com/mcp
```

## Connect

### Claude (web, desktop and mobile)

1. In Claude, open the connector settings and add a **custom connector**.
2. Enter a name, for example `Manage Runners`, and the URL `https://api.managerunners.com/mcp`.
3. Select **Connect**. Your browser opens the Manage Runners consent page; see [Allow access](#allow-access).

On Team and Enterprise plans, an owner may have to add custom connectors for the organization first.

### Claude Code

```sh
claude mcp add --transport http manage-runners https://api.managerunners.com/mcp
```

Then run `/mcp` in Claude Code, select `manage-runners` and authenticate, or run `claude mcp login manage-runners`. Claude Code opens the consent page in your browser.

### Other MCP clients

Other AI assistants and editors can connect if they support remote MCP servers over Streamable HTTP with MCP authorization, that is OAuth sign-in where the client registers itself (dynamic client registration or a client ID metadata document). Clients that run inside a web page are not supported: the server refuses requests a browser page sends. This page describes the setup for Claude and Claude Code only; in other clients the menus differ.

1. Add a remote MCP server with the URL `https://api.managerunners.com/mcp`. The transport is Streamable HTTP. No API key or extra header is needed.
2. Sign in when your client asks. The client registers itself with Manage Runners and opens the consent page in your browser; see [Allow access](#allow-access).
3. After you decide, your browser returns to the client. Clients that return through an app link are supported when its scheme is reverse-domain style, such as `com.example.app:/…`, or belongs to a listed client such as Cursor (`cursor://…`): your browser asks whether to open the app. If nothing happens, check that the app is installed and start the connection again from it.

Permissions, confirmations and the dashboard step work the same in every client. To end a connection, see [Disconnect](#disconnect).

## Allow access

The consent page at `app.managerunners.com` asks you to sign in, including multi-factor authentication if you use it. Your email address must be verified. The page shows:

- the app's name, and the domain that publishes the app if it is identified by a published address, as Claude is (`claude.ai`); for apps that registered themselves, the page notes that the name is not verified,
- where you return after deciding, for example `claude.ai`, a program on your own computer for Claude Code, or the app a link opens, such as `cursor://anysphere.cursor-mcp`,
- the permissions the app asked for.

Permissions that only read are preselected. Permissions that change runners or cost money are off until you select them. Allow only what you want your assistant to do; you can connect again later to grant more.

If the page warns that the app returns to a program on your computer, or through a link that opens an app, continue only if you just started the connection yourself, for example with `claude mcp add`. Another program or app on your device could otherwise receive the access.

## Permissions

The connector uses the same scopes as [personal access tokens](https://managerunners.com/docs/manual/access-tokens/#scopes). In each organization, your assistant can do at most what both the permissions you granted and your role allow.

| Permission | Tools |
| --- | --- |
| Read profile (`profile:read`) | `whoami`: your account, this connection's permissions and your organizations |
| Read subscription (`subscriptions:read`) | `get_subscription` |
| Read runners (`runners:read`) | `list_runners`, `get_runner`, `get_runner_metrics`, `list_caches`, `get_cache`, `list_metrics_connections`, `get_metrics_connection` |
| Read products (`products:read`) | `list_products`: server types, locations and prices |
| Read SSH keys (`providers:ssh-keys:read`) | `list_ssh_keys` of a runner's Hetzner project (Owner or Editor) |
| Read schedules (`schedules:read`) | `get_schedule` (Pro or Enterprise plan) |
| Manage runners (`runners:write`) | `create_runner`, `pause_runner`, `resume_runner`, `duplicate_runner`, `update_runner`, `test_cache`, `create_cache`, `update_cache`, `delete_cache`, `create_metrics_connection`, `update_metrics_connection`, `delete_metrics_connection` |
| Manage schedules (`schedules:write`) | `set_schedule`, `enable_schedule`, `disable_schedule`, `delete_schedule` (Pro or Enterprise plan) |
| Delete runners (`runners:delete`) | `delete_runner` |
| Remove unknown runners (`runners:forget`) | `forget_runner` |

Your assistant only sees the tools your permissions allow. Tools work in your default organization; ask your assistant to use another one by name, and it passes that organization's id from `whoami`.

Caches show their access key ID but never the secret key, and metrics connections show header names but never their values.

The connector never asks for your GitLab runner token, Hetzner API token, S3 secret key or metrics header values, and you should never paste them into a chat. Changing a runner's tokens, billing, organizations, members and access tokens stay in the [dashboard](https://app.managerunners.com).

## Finish in the dashboard

Some changes need a secret: creating a runner (GitLab runner token and Hetzner API token), creating a cache or giving it a new secret key, and adding or replacing a metrics connection's header values. For these, your assistant checks the settings first, for example the server type, location, plan and the cache or metrics connection you named, and shows you the configuration and, for a runner, the net monthly list price. It then gives you a link to `app.managerunners.com`.

1. Open the link and sign in with the account you connected, including multi-factor authentication. Another account cannot open it.
2. Check the settings shown. They are read-only; to change them, ask your assistant to prepare the change again.
3. Enter the secrets and confirm. A cache's connection can be tested first. Nothing is created or changed before you confirm.
4. Go back to your assistant and say you are done. It then checks the result, for example with `list_runners`.

A link works once and for 30 minutes, and only while the connection that created it is connected and you may still manage runners in that organization. If the Hetzner token is rejected or an SSH key is not in its project, the page says so and you can correct it on the same link. Links keep working if Manage Runners is restarted or updated meanwhile. If saving your confirmation does not finish within the expected time, for example because of such a restart, the page says the outcome is unknown; ask your assistant to check before trying again. You can normally have up to 50 open links.

The secret part of the link comes after `#`, so opening the link does not send it to any server; the page passes it to Manage Runners only inside its requests, never in an address. The page removes it from the address bar as soon as it opens and keeps it only in that browser tab, also while you sign in; to open the change in another tab or browser, use the link from your assistant again.

If an update changes a cache or metrics connection that runners use, the page lists them; active runners get a new server. Confirm that on the page.

Manage Runners only applies what the page showed you. If the server type, its listed price, the cache or metrics connection, or the runners using them change before your confirmation is saved, nothing is created or changed and the page asks you to check again. If the server type, cache or metrics connection was removed altogether, the page says so; ask your assistant to prepare the runner again. The price is Hetzner's current net list price, shown for your information; Hetzner bills its own prices. If the cache or metrics connection itself changed after your assistant prepared the update, ask it to prepare the update again. Once a link has expired or the connection was disconnected, it no longer shows the result either; check it in the dashboard. The page reports an expired link as expired for at least an hour, and after that as invalid or expired.

## Confirmations

Changes that cost money or replace a server happen in two steps:

- **Resume** and **duplicate** create a new Hetzner server, which Hetzner bills to your project.
- **Update** of an active runner's server type, GitLab host, concurrency, executor, SSH keys, cache, monitoring or metrics connection deletes and recreates its server. Renaming a runner or changing its labels does not.
- **Updating a cache's connection or a metrics connection's endpoint or headers**, and **deleting a metrics connection**, recreate the servers of the active runners that use it; runners in state **Unknown** keep the previous settings until they are recreated. Renaming does not recreate anything.

For these, your assistant first gets a preview with the effect, the affected runners and, for a runner, the current net monthly list price, for your information, and should ask you before it applies the change. The confirmation is valid for five minutes, once, for exactly the previewed change. If the runner, cache or metrics connection changes in the meantime, for example because someone resizes the runner in the dashboard, nothing happens and your assistant has to show you a new preview.

Runners in state **Unknown** cannot be updated with `update_runner`; check them in the dashboard first.

**Delete** and **forget** need the exact runner id twice. Forget only removes a runner in state **Unknown** from Manage Runners; its Hetzner server, if it still exists, is not deleted. Deleting a cache or metrics connection also needs its id twice. A cache that runners still use cannot be deleted; deleting a metrics connection switches Metrics off on the runners that use it.

Your client may also ask you before it runs a tool; Claude does, unless you allowed that tool permanently.

If a change fails in a way that leaves its outcome unknown, for example because Hetzner did not answer, your assistant is told not to retry it but to check the runner first. Retrying a change with the same confirmation never applies it twice; if the change already went through, your assistant gets its original result.

## Limits

Each connection can make 120 tool calls per minute, and 30 calls to tools that change things per 10 minutes; previews, dashboard links and cache tests count towards these. Beyond that, the tool answers with how long to wait.

## Disconnect

Open **Settings** (your profile) and go to **Connected apps**. It lists every connection with its permissions and when it was last used. Select **Disconnect** to end a connection; your assistant loses access immediately. To use it again, connect again from your assistant.

A connection that is not used for 30 days expires and has to be connected again. Removing the server in your client, for example the connector in Claude or `claude mcp remove manage-runners` in Claude Code, removes it on the client's side; disconnect it in Manage Runners as well to end it here.

## Troubleshooting

- **The consent page says the request has expired:** you have 10 minutes to sign in and decide. Start the connection again from your assistant.
- **The page says the link is invalid:** open the link from your assistant again in this tab; a copy of the address bar no longer contains it.
- **A dashboard link has expired, was already used or belongs to another account:** ask your assistant to prepare the change again, signed in with the account you connected. If the page says the app was disconnected, connect your assistant again first.
- **"Verify your email address before connecting apps":** enter the code from the verification email on the consent page or in [your profile](https://managerunners.com/docs/manual/account-security/).
- **A tool answers `SUBSCRIPTION_REQUIRED`:** metrics need a paid plan, and schedules a Pro or Enterprise plan, for the organization. See [Billing and plans](https://managerunners.com/docs/manual/billing/).
- **A tool answers `ORGANIZATION_PERMISSION_DENIED`:** your role in that organization does not allow it, for example a Viewer pausing a runner. See [Organizations](https://managerunners.com/docs/manual/organizations/).
- **Your assistant cannot use a tool you expected:** the connection lacks its permission. Connect again and select it on the consent page; in Claude Code, select **Re-authenticate** in `/mcp`.