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 |
|
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 | |
Europe |
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.
- Open Claude's connector settings and add the Cycle connector for your region.
- For EU search for
Cycle (EU) - For NA search for
Cycle (North America) - Sign in to Cycle: the sign in will ask for your Cycle account username and password, plus 2FA if you have it enabled.
- Choose the hub this connection should reach.
- 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
/mcpandclaude 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,
/mcplists 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"
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 |
|---|---|---|
|
| Just you, just this project. The right default for anything with a key in it. |
|
| Just you, every project. |
|
| 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 |
|
CLI | the name you passed to |
|
Pre-approve the ones you use constantly in .claude/settings.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.
- 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.
- Go to Settings → Apps → Create.
- Provide the endpoint: your region's URL from above.
- Pick the authentication mechanism. Cycle uses OAuth.
- Click Scan Tools and wait for it to finish, ChatGPT inspects what the server exposes.
- Complete the OAuth authorization: sign in to Cycle, pick the hub, tick the tiers.
- 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/
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 |
|
ChatGPT | Re-run Scan Tools on the app. Nothing returned means the endpoint or the OAuth step is the problem. |
Codex |
|
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 Codecodex 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.