Use CloudCLI as an MCP server

Use CloudCLI's hosted MCP server to let an MCP-compatible assistant manage the CloudCLI environments you own. This is different from Settings → Shared Setup → MCP, where you configure third-party MCP servers that CloudCLI installs inside your environments.

Before you start

You need a CloudCLI account and an MCP client that supports remote Streamable HTTP servers. There are two ways to authenticate:

• OAuth — for clients such as claude.ai that connect with a sign-in flow instead of credentials you paste in.
• API key — for clients such as Claude Code or Cursor that can send a custom authorization header.

The CloudCLI MCP server URL for both is https://cloudcli.ai/api/mcp.

Connect with OAuth (claude.ai and similar clients)

1. In your MCP client, add a custom connector with the URL https://cloudcli.ai/api/mcp.
2. The client discovers CloudCLI's sign-in service and registers itself automatically.
3. Your browser opens CloudCLI. Sign in if needed, review what the app is requesting, and choose Allow access.
4. The client finishes connecting on its own. No key or secret is copied at any point.

Apps you have approved appear in Settings → Developer Access under Authorized apps, where you can revoke any of them at once. Revocation takes effect immediately.

Connect with an API key

1. Open Settings → Developer Access.
2. Create a dedicated API key for your MCP client. Copy it when it is shown; CloudCLI cannot display the full key again.
3. Add the server to your MCP client and send the API key as a Bearer token.

A generic configuration looks like this. Adapt the environment-variable syntax to your client:

{
  "mcpServers": {
    "cloudcli": {
      "type": "http",
      "url": "https://cloudcli.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CLOUDCLI_API_KEY}"
      }
    }
  }
}

Keep the API key in your client's secret or environment configuration. Do not paste it into a prompt or commit it to a repository.

Available tools

The first release exposes six security-reviewed tools:

• List your environments
• Create an environment
• Get one environment
• Start an environment
• Stop an environment
• List supported agent models

Stopping an environment is marked as destructive so clients can request confirmation. Delete, SSH credential retrieval, GitHub tokens, and agent execution are not exposed. All environment operations use the same ownership and account checks as CloudCLI itself.

CloudCLI generates the tool catalog from its OpenAPI definition, but an API operation appears only after an explicit MCP security opt-in. New API endpoints therefore do not become agent-accessible merely because they were added to the API.

Authentication and revocation

Both authentication methods grant the same access: the connected assistant can act only on environments owned by your account.

• OAuth connections are listed under Authorized apps in Developer Access. Revoking one signs that app out immediately.
• API keys should be created one per client so you can revoke access without affecting another integration. To rotate a key, create a replacement, update the client, verify the connection, and delete the old key.

Troubleshooting

• Couldn't register / sign-in failed (OAuth): Try connecting again; if it persists, remove the connector and add it again to restart the sign-in flow.
• Unauthorized (API key): Confirm the header uses Authorization: Bearer ccui_... and that the key is still active.
• Unauthorized after working before (OAuth): The app's access may have been revoked under Authorized apps. Reconnect to authorize it again.
• Tool not found: Refresh the MCP server in your client. Only explicitly reviewed operations are available.
• Environment not found: The connected account can access only environments it owns.