Connect your agent (MCP)

Helicarrier speaks MCP (Model Context Protocol), so you can drive your whole account from an AI agent — Claude, Cursor, or anything that speaks MCP. Ask it to deploy a service, tail logs, set an environment variable, roll back a bad deploy, or provision a database, and it calls Helicarrier for you.

There are two ways to connect, and the right one depends on your client.

Connect with OAuth (recommended)

If your client can add a custom connector by URL — Claude’s connector settings, and most agent UIs — just give it:

https://app.helicarrier.xyz/mcp

Leave the optional OAuth client ID and secret blank. The client registers itself, sends you to Helicarrier to sign in, and shows a consent screen where you choose what it may do:

• Read-only (default) — view projects, services, deployments, logs and metrics. It cannot deploy, change settings, or delete anything.
• Full access — everything above, plus deploying, changing configuration, and deleting services and databases.

Approve, and the client is connected. Nothing is granted until you approve, and the connection appears in Settings → Your account → API keys, where you can revoke it at any time. OAuth connections expire after 30 days and refresh themselves while they stay connected.

Pick read-only unless you actually want the agent making changes. You can reconnect with full access later.

Connect with an API key

Clients configured from a file — Claude Code, Cursor’s mcp.json, your own scripts — take a key directly. Keys do not expire.

First, create an API key. For an agent, prefer the narrowest scope that does the job — a project-scoped or service-scoped key rather than an account-wide one. A scoped key connects exactly the same way; the agent’s tools simply resolve to that project or service, and it can call the whoami tool to discover its own scope.

Point your MCP client at the endpoint

The endpoint is shown on the same page:

https://app.helicarrier.xyz/mcp

Configure your MCP client with that URL and an Authorization: Bearer header carrying your key. For a client that uses a JSON config, it looks like:

{
  "mcpServers": {
    "helicarrier": {
      "url": "https://app.helicarrier.xyz/mcp",
      "headers": { "Authorization": "Bearer heli_your_key_here" }
    }
  }
}

(Exact config varies by client — use its “remote/HTTP MCP server” option and set the URL + Authorization header.)

Ask your agent

Once connected, your agent can:

• See things — list projects and services, read a service’s status, deployments, logs, env keys, and domains. get_metrics takes a range (1h, 6h, 24h, 7d) so you can ask about a pattern rather than just the last hour, and get_deployment_logs takes after so an agent can follow a build as it runs instead of re-reading the whole log.
• Ship things — create a service (from a Git repo, an image, or an uploaded folder with deploy_upload), deploy, roll back, scale, stop, or delete it. deploy_service takes an optional ref, so you can ask for “deploy tag v1.2.3” or a specific commit without changing the branch the service tracks. scale_service sets the instance count and can turn autoscaling on with CPU/memory targets.
• Configure things — set environment variables, add a custom domain, provision a managed database.

Environments

A project’s services are returned one environment at a time. get_project reads the project’s default environment unless you pass env, so if your agent can’t find a service you know exists, it is almost always looking at the wrong environment:

“List the services in checkout’s staging environment.”

Ask it to call list_environments first to see the slugs a project has, then get_project with env. create_service and deploy_upload take the target environment the same way — and if your API key is restricted to particular environments, passing it is required rather than optional (whoami tells you whether yours is).

One thing to watch when reading list_projects: serviceCount is the true total, but the services array beside it is only a small preview of service types for the dashboard’s project card — capped at eight, with no ids or names. Use get_project for the real list.

The deploy_upload tool lets an agent deploy local code with no git repo: pipe your project folder as a base64-encoded .tar.gz. Keep it to source (exclude node_modules/.git); very large contexts should use the dashboard upload flow.

Destructive actions (deploy, rollback, delete, scale, env changes, and the like) are flagged, so a well-behaved client will confirm with you before running them. If you created a read-only key, those tools aren’t offered at all.

Your projects are also exposed as MCP resources, so a client that supports resources can attach a project (its services, environments, and config) as context for the conversation.

Note

An account-wide key carries the account access of its owner; project and service keys are narrower. Treat every key like a password: don’t paste it into shared configs, and revoke it if it may have leaked.

Reference and automation

• MCP tool reference — every tool, its required inputs, and its corresponding REST operation.
• REST API guide — authenticate, inspect scope, and follow a deployment from a script.
• OpenAPI specification — import the documented automation endpoints into API tooling.