MCP Integration

Rock8Cloud exposes an MCP (Model Context Protocol) server that lets AI coding agents interact with your projects, services, environments, and code reviews.

Available Tools

Setup

The MCP server URL for your instance is:

https://app.rock8.cloud/mcp

Authentication is handled via OAuth - each agent will prompt you to authorize on first use.

ChatGPT

1. Open ChatGPT Plugins, select +, then Add custom MCP server. If the option is missing, turn on Developer mode under Settings → Apps → Advanced settings.
2. Name it rock8cloud, enter https://app.rock8.cloud/mcp as the public endpoint and pick OAuth authentication.
3. Select Create as a plugin and sign in to Rock8Cloud when asked.
4. Start a new conversation and ask, for example, "Show me what is deployed on rock8cloud".

After Rock8Cloud ships new tools, select Refresh on the plugin to pick them up.

Claude Code

claude mcp add rock8cloud --transport http https://app.rock8.cloud/mcp

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "rock8cloud": {
      "type": "http",
      "url": "https://app.rock8.cloud/mcp"
    }
  }
}

Pi

Pi requires an MCP extension. Install the Pi MCP Adapter:

pi install npm:pi-mcp-adapter

Add the server to your project's .mcp.json:

{
  "mcpServers": {
    "rock8cloud": {
      "url": "https://app.rock8.cloud/mcp",
      "auth": "oauth"
    }
  }
}

Restart Pi, then authorize Rock8Cloud from inside Pi:

/mcp-auth rock8cloud

Complete the browser authorization flow. You can inspect the connection later with /mcp.

Zed

Zed does not support remote HTTP MCP servers natively yet. Use mcp-remote as a stdio bridge. Add to your project's .zed/settings.json (or global ~/.config/zed/settings.json):

{
  "context_servers": {
    "rock8cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.rock8.cloud/mcp"]
    }
  }
}

OpenCode

Add to your project's opencode.json:

{
  "mcp": {
    "rock8cloud": {
      "type": "remote",
      "url": "https://app.rock8.cloud/mcp"
    }
  }
}

then run opencode mcp auth to authorize

OpenAI Codex CLI

codex mcp add rock8cloud --url https://app.rock8.cloud/mcp

Or update your ~/.codex/config.toml:

[mcp_servers.rock8cloud]
url = "https://app.rock8.cloud/mcp"

IntelliJ

Open Settings → Tools → AI Assistant → Model Context Protocol, click Add, choose STDIO, and paste:

{
  "mcpServers": {
    "rock8cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.rock8.cloud/mcp"]
    }
  }
}

Troubleshooting

If your MCP client uses mcp-remote as a bridge (like Zed or IntelliJ), you might occasionally encounter the following error when calling tools:

JWKSNoMatchingKey: no applicable key found in the JSON Web Key Set

This happens when the OAuth key set rotates and the cached token states fall out of sync. To fix this, entirely remove your local cached credentials directory:

rm -rf ~/.mcp-auth

This ensures mcp-remote will prompt you for a clean, brand new OAuth access token flow on the next tool execution.

First Deploy Workflow

The MCP server includes a first_deploy prompt template that guides AI agents through deploying a repository for the first time. The flow:

1. Validate locally - agent checks for a Dockerfile (creates one if missing), reads the EXPOSE port, ensures changes are committed and pushed
2. Check GitHub connection - check_github_connection verifies the GitHub App can access the repository
3. Create project - create_project creates a new project to group your services
4. Select branch - list_branches lets you pick which branch to deploy
5. Create service - create_repo_service registers the service with its Dockerfile and port configuration
6. Deploy - deploy_service triggers the build and deployment, returns the URL where your app will be live

To start a first deploy, ask your AI agent to "deploy this repository" or use the first_deploy prompt if your agent supports MCP prompts.

Agentic Develop Workflow

The mirror of the first deploy, for a repo that is not ready to run. The agentic_develop prompt brings the repository in and puts an agent on it, without deploying anything. See Agentic Develop for how the same thing works from the dashboard.

Creating a service never deploys it, so the flow is the first deploy with the last step left off, plus one flag that keeps pushes from deploying:

1. Check GitHub connection - check_github_connection, exactly as above
2. Create project - create_project, or reuse one
3. Create service - create_repo_service with autoDeploy: false. The service is created with its Deploy on Push workflow turned off. If the repo has no Dockerfile yet, pass Dockerfile and 3000 as placeholders. They are stored build settings and build nothing, and edit_service corrects them later
4. Stop - no deploy_service call. The service exists and nothing runs, so no pods and no build minutes are used. Its allocation still counts against your resource pool, the same as any other service
5. Work on it - task_agent starts a coder or research session on the new service, and get_agent_run returns the result

Pushes from your agents, and pull requests you merge, do not deploy the service, whether or not the repo has a Dockerfile. Agents are still told not to add a Dockerfile in this flow, because making the service runnable is your call. When you want it live, run deploy_service or press Manual deploy once a Dockerfile exists, and turn on Deploy on Push in the service's Workflows tab if pushes should deploy it from then on.

To start one, ask your agent to "add this repository to Rock8Cloud but do not deploy it", or use the agentic_develop prompt.

Blueprint Deploy Workflow

A blueprint is a ready-made stack. Deploying one used to mean opening the dashboard - an agent can now do the whole thing:

1. Pick a blueprint - list_blueprints returns the slug, name, one-line summary and stack tags of everything published
2. Pick a GitHub account - list_github_owners returns the accounts the template can be forked into. An empty list means nobody has installed the Rock8Cloud GitHub App for this organization yet
3. Deploy - deploy_blueprint takes the slug, a project name and the owner. It forks the template repository, creates the project with its services and databases, and starts the first deploy on its own - there is no separate deploy_service call. For a blueprint that needs AI, the agent asks for your provider's OpenAI-compatible base URL first, and deploy_blueprint refuses to deploy it until it passes your answer. You enter the API key and any other secret input on the service's Environment Variables page after the deploy, unless you give it to the agent yourself
4. Monitor - the response carries a serviceId per created service. Poll each one with get_deployment_status. It also carries the blueprint's post-deploy notes, and bootstrapFailures for any service whose first deploy could not be started and needs a manual redeploy
5. Build - once it is live, an agent with a local workspace (Codex, Claude Code, OpenCode) clones the forked repository and builds your prototype there. Every push redeploys it. Without a workspace, as in ChatGPT on the web, the agent gives you the repository and the live URL to continue in your editor

When you ask an agent to build or prototype a working app - something with a backend, a database, a login or that you want to keep developing - it offers once to start it from the closest blueprint. The code lands in your GitHub account with a Dockerfile, so you own it and can run it anywhere. Static mockups and HTML previews are published as pages instead.

Deploying forks real repositories into your GitHub account and creates billed services, so agents are instructed to confirm the blueprint, project name and owner with you first. If a deploy fails halfway, the error names the repositories it already forked so you know what to delete before retrying.

Code Review Workflow

The get_code_reviews tool is designed for agents running inside a repository. A typical workflow:

1. Agent detects the current branch (git branch --show-current) and remote (git remote get-url origin)
2. Agent calls get_code_reviews with the branch and repo URL - the tool searches every organization the token can access, so no org lookup is needed
3. Agent receives findings with severity, file locations, and fix suggestions. If nothing matches, the response explains why - for example the branch was never pushed, no PR is open, or none of the accessible organizations host the repo
4. Agent discusses findings and can apply fixes using the fixPrompt field

This lets you interactively resolve code review feedback without leaving your editor.

Agent Sessions Workflow

The agent tools let your AI assistant delegate work to a Rock8Cloud agent running in a cloud sandbox with its own copy of the repo. The API key needs the read:agents and write:agents scopes. A typical workflow:

1. Task - task_agent with a service, an agent type (coder implements changes and opens a PR, research is read-only) and the task. Optionally pin an AI model by passing a modelId from list_agent_models - without it the session uses the platform default. It returns sessionId and runId immediately - runs take minutes
2. Poll - get_agent_run every 15-30 seconds until done is true. On success it carries the agent's reply, files changed, commit and PR link. A non-null pendingQuestion means the agent is waiting for an answer
3. Iterate - continue_agent_session sends follow-up turns to the same session. Suspended sessions resume automatically from their workspace snapshot with full context. Continuing a closed session creates a new session from the base branch, seeds it with the latest handoff, and returns the new sessionId. Use that returned ID for polling and later turns
4. Inspect - get_agent_session returns the conversation, the latest handoff brief (the agent's memory) and session status. list_agent_sessions finds existing sessions
5. Finish - sessions park themselves when idle and cost nothing while parked. Use close_agent_session only when the work is truly done - closing is permanent

Uptime Status

The read-only get_uptime_status tool returns a repository service's monitored URL, current availability, 30-day uptime ratio, average response time, last check, and daily outage history. The OAuth client needs the read:uptime-monitors scope.

Dependency Vulnerabilities

The read-only list_vulnerabilities tool returns the critical dependency vulnerabilities found by the lockfile scan of each repo service's latest stable build, for the whole organization or for one service with serviceId. Each finding names the CVE, the package, the installed and fixed version, and the lockfile. A critical finding blocks the deploy.

Scanning is opt-in per service (see Service Configuration). Services with scanning off, or never scanned, are listed without findings, and an agent can turn scanning on with edit_service (dependencyScanEnabled). The OAuth client needs the read:deployments scope.

Dashboard views in ChatGPT and Codex

In ChatGPT and Codex, these tools render live views of your organization inside the conversation. Other MCP clients get the same data as a text summary.

Writing Environment Variables

write_manual_env_vars lets an agent create or update manual (plaintext) environment variables on a service, such as an API key or a config value you give it directly. Since these values may be secrets, agents are instructed to ask you to confirm the exact key/value pairs before writing anything. If an agent tries to write env vars without asking, stop it and ask it to confirm with you first.

Values are never read back to the agent. Use get_env_vars to check which keys already exist - manual values are always shown masked as ***.

Assistants never ask you for API keys, tokens or passwords. They link the service's Environment Variables page in the dashboard, where you enter them yourself, and then redeploy. If you paste a key into the chat anyway, it is still written. Blueprints start with their secret inputs empty unless you give them.

Verify Connection

After setup, verify the MCP server is connected:

Claude Code:

claude mcp list

Pi: Run /mcp. rock8cloud should appear in the server list.

Other agents: Check the MCP or tools panel in your IDE settings - rock8cloud should appear with the tools listed above.