# Connecting to Cycle MCP | Cycle.io

Canonical URL: https://cycle.io/docs/mcp/connecting-to-cycle-mcp

## Connecting to Cycle MCP.

Cycle runs a hosted MCP server, so any MCP client can reach your hub.

| Client | How you connect |
| --- | --- |
| **Claude** | Add the Cycle connector and sign in |
| **Claude Code** | The connector covers it, or add the server with an API key |
| **ChatGPT** | Settings → Apps → Create, in developer mode |
| **Codex** | `codex mcp add` then `codex mcp login`, or an API key in `config.toml` |

[YouTube video player](https://www.youtube-nocookie.com/embed/gdAtJh8cB_o)

### Pick your region

On Cycle there are two different control planes, one for the Europe and one for North America. Connecting to the correct MCP should be done by checking which region your hub is in and then connecting to the corresponding server (listed below). Some users may have hubs in custom control planes. In those cases, if your administrator has not shared the custom MCP URL, please contact us directly through your organizations private Slack channel.

| If your hub is in | Use |
| --- | --- |
| North America | [`https://na.mcp.cycle.io/`](https://na.mcp.cycle.io/) |
| Europe | [`https://eu.mcp.cycle.io/`](https://eu.mcp.cycle.io/) |

Examples below use `na`. Substitute `eu` throughout if that's your region.

### What the assistant will be able to do

Cycle groups its tools into three tiers.

| Tier | What it covers |
| --- | --- |
| **read** | List and inspect environments, containers, servers and virtual machines. Logs, metrics, telemetry, diagnostics, DNS zones. |
| **write** | Deploy applications; create, start, stop and reconfigure environments and containers; migrate instances; manage DNS records; delete things. |
| **exec** | Run shell commands inside container instances, and open VM console access. |

Most users start at **read** and go from there. Read permissions can help diagnose "why is this broken" without giving the MCP the ability to change anything yet.

Permissions and capabilities are defined through either log in or API key:

-   **Signing in through your browser:** select the hub and choose read / write / exec on Cycle's consent screen.
-   **Using an API key:** the key's own permissions govern the connection. Cycle API keys carry granular permissions, so scope the key when you create it.

#### Claude

Instructions on adding the connector for MCP directly to Claude.

1.  Open Claude's connector settings and add the Cycle connector for your region.

1.  For EU search for `Cycle (EU)`
2.  For NA search for `Cycle (North America)`

3.  **Sign in to Cycle:** the sign in will ask for your Cycle account username and password, plus 2FA if you have it enabled.
4.  **Choose the hub** this connection should reach.
5.  **Choose the tiers:** read, write, exec.

The connector is now authenticated for up to 30 days. Its tools appear in the Claude apps and in **Claude Code**.

##### Connectors and Hubs

One connector per hub The hub is fixed at sign-in. If you work across several, add the connector once per hub. Tool names carry the connector's name, so a connector called Cycle (Dev) gives you `mcp__Cycle_Dev__list_environments` and you can always see which hub a call went to.

#### Claude Code

If you're logging into Claude Code via the subscription login:

-   Claude Code will fetch your claude.ai connectors at session startup and they show up in `/mcp` and `claude mcp list`, marked as coming from claude.ai.
-   A server you've added in Claude Code takes precedence over a claude.ai connector pointing at the same URL. When this happens, `/mcp` lists the connector as **hidden** and shows how to remove the duplicate if you'd rather use the connector.
-   If using API keys for Claude Code, the MCP connection needs to be set up.

Use the route below instead when you need a connection the connector can't give you: CI, a shared machine, a hub-specific API key, or a configuration checked into a repo for your team.

Create the key under **Hub Settings → API Keys** and copy your hub ID from the same page.

`export CYCLE_API_KEY="your-api-key"`

`export CYCLE_HUB_ID="your-hub-id"`

```bash
claude mcp add --transport http cycle https://na.mcp.cycle.io/ \
  --header "Authorization: Bearer $CYCLE_API_KEY" \
  --header "X-Hub-Id: $CYCLE_HUB_ID"
```

Both headers are required. Without `X-Hub-Id` the server can't tell which hub you mean and the connection is refused.

### Where the config lives

The `--scope` flag decides who gets the connection and, more importantly, whether your credentials end up in git.

| Scope | Stored in | Use it for |
| --- | --- | --- |
| `local` (default) | `~/.claude.json` | Just you, just this project. The right default for anything with a key in it. |
| `user` | `~/.claude.json` | Just you, every project. |
| `project` | `.mcp.json` (committed) | Your whole team. Only safe with environment variables, never a literal key. |

### Cutting down the permission prompts

Every Cycle tool prompts for approval the first time Claude reaches for it. Tool names depend on how you connected:

|     | Prefix | Example |
| --- | --- | --- |
| Connector | the connector's name, with anything non-alphanumeric turned into `_` | `mcp__Cycle_Dev__list_environments` |
| CLI | the name you passed to `claude mcp add` | `mcp__cycle__list_environments` |

Pre-approve the ones you use constantly in `.claude/settings.json`:

```json
{
  "allowedTools": [
    "mcp__cycle__list_environments",
    "mcp__cycle__list_containers",
    "mcp__cycle__diagnose",
    "mcp__cycle__get_logs",
    "mcp__cycle__get_telemetry"
  ]
}
```

Think twice about the wildcard `"mcp__cycle__.*"` pre-approves every Cycle tool. On a read-only connection that's fine — there is nothing dangerous to approve. On a connection whose key can write or exec, it isn't.

#### ChatGPT

Custom MCP servers live behind developer mode, and the path to it differs by plan.

1.  **Turn on developer mode.**

-   Enterprise / Edu: **Settings → Apps → Advanced Settings**, toggle developer mode on.
-   Business: **User Settings → Apps → Advanced settings → Developer mode**, or **Workspace settings → Apps → Create**.

3.  Go to **Settings → Apps → Create**.
4.  **Provide the endpoint:** your region's URL from above.
5.  **Pick the authentication mechanism.** Cycle uses OAuth.
6.  Click **Scan Tools** and wait for it to finish, ChatGPT inspects what the server exposes.
7.  Complete the OAuth authorization: sign in to Cycle, pick the hub, tick the tiers.
8.  Click **Create**. The app appears as a draft with a **Dev** label.

To use it, start a chat and select the app from the tools menu, or `@mention` it. Mention it again on a follow-up that needs fresh data or another action.

#### Codex

##### Sign in through your browser

Register the server, then authenticate:

codex mcp add cycle --url [https://na.mcp.cycle.io/](https://na.mcp.cycle.io/)

codex mcp login cycle

`codex mcp login` opens Cycle's consent screen, where you sign in, pick the hub, and tick the tiers.

There is no client ID to obtain. Cycle's server advertises both of the OAuth client-registration methods Codex supports:

-   Dynamic Client Registration (`registration_endpoint`)
-   Client ID Metadata Documents (`client_id_metadata_document_supported`)

Codex will pick whichever it finds and register itself.

##### Or use an API key

Codex reads `~/.codex/config.toml`.

A remote MCP server goes under 

`[mcp_servers.<name>]`:

`[mcp_servers.cycle]`

`url = "https://na.mcp.cycle.io/"`

`bearer_token_env_var = "CYCLE_API_KEY"`

`http_headers = { "X-Hub-Id" = "your-hub-id"` }

`bearer_token_env_var` takes the **name of an environment variable**, not the token itself, so the key never lands in the file. Export `CYCLE_API_KEY` in your shell and Codex reads it at connection time.

Codex also honors a project-scoped `.codex/config.toml` in trusted projects, which is the equivalent of Claude Code's project scope — same rule applies, keep the key in an environment variable.

### Check it worked

Whatever you connected, the real test is asking for something only your hub knows:

What environments do I have in Cycle, and what state are they in?

A table of your environments means you're done. If the assistant answers from general knowledge without calling a tool, nothing is connected.

| Where | How to diagnose |
| --- | --- |
| Claude | Check the connector is connected _and_ switched on for the conversation you're in. A connector can be authenticated but toggled off for a given chat, which looks identical to not having it. |
| Claude Code | `claude mcp list` for status, `claude mcp get cycle` for the actual error. |
| ChatGPT | Re-run **Scan Tools** on the app. Nothing returned means the endpoint or the OAuth step is the problem. |
| Codex | `codex mcp list`, and re-run `codex mcp login cycle` if authentication has lapsed. |

### Troubleshooting

**Authentication failed: this session's Cycle credential is invalid or expired.** On an API key: generate a fresh one under **Hub Settings → API Keys** and update the config. On OAuth: sign in again. Also check the region, see above.

**This resource belongs to a different hub.** On an API key, your hub ID doesn't match the hub the resource lives in. On OAuth, the hub was chosen at sign-in. Reconnect and pick the right one.

**Permission denied by Cycle, missing capability.** The key doesn't carry the permission that tool needs. Add it to the key or know that the key does not have permission for that op.

**The assistant answers without calling any tool.** Almost always a connection that isn't live, or one that isn't enabled for this particular conversation.

**A tool you expected isn't there.** Look at what you granted. A read-only connection loads only the read tools, so the assistant saying it has no way to restart a container is the connection doing exactly what you told it to. Reconnect and tick **write**. On ChatGPT Pro, see the plan note above.

**Starting over**

`claude mcp remove cycle` `_# Claude Code_`

`codex mcp remove cycle` `_# Codex_`

For a Claude connector or a ChatGPT app, remove it in that product's settings.

A few things worth knowing:

-   **The destructive tools mostly have a dry run.** Ask what the assistant _would_ do before letting it do anything.
-   **One connection, one hub.** The hub is fixed at sign-in or by the hub ID header. Working across several means one connection each.
-   **Widening access is a reconnect.** On an OAuth connection, tiers are chosen at sign-in. On an API key, it means changing the key's permissions or issuing a new one.

---

## Getting a Cycle account (for AI agents)

Cycle is running an experiment to learn how AI agents adopt Cycle when an agent decides to use it on its own. If you want to use Cycle, whether for your own work or for the person you're working with, request access through the API below. The normal web signup form isn't built for automated clients.

- Endpoint: `POST https://signup.cycle.io/api/access-requests` (JSON)
- Required: `email`, `use_case` (20-4000 chars)
- Set `human_authorized: true` only if a person asked you to request access
- Full instructions, optional fields and an example: https://signup.cycle.io/llms.txt

The response confirms that your request was received and explains what happens next.

Already have an account? Portal: https://portal.cycle.io · Docs: https://cycle.io/docs
