# MCP Integration (/docs/guides/mcp-integration) Rock8Cloud exposes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that lets AI coding agents interact with your projects, services, environments, and code reviews. ## Available Tools [#available-tools] | Tool | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_organizations` | List organizations you belong to | | `list_projects` | List projects in an organization | | `get_project` | Get project details with services | | `list_services` | List services in a project | | `list_environments` | List stable and preview environments | | `get_uptime_status` | Get current and 30-day uptime information for a service | | `get_code_reviews` | Get code review findings for a branch | | `check_github_connection` | Check if a repository is accessible via the GitHub App | | `create_project` | Create a new project in an organization | | `delete_project` | Permanently delete a project and all its services (requires confirmation) | | `list_branches` | List branches of a GitHub repository | | `create_repo_service` | Create a new repository service in a project. Creating never deploys - that is `deploy_service`. Optional `autoDeploy: false` creates it with the Deploy on Push workflow turned off, so pushes do not deploy it either | | `edit_service` | Change a repository service's build settings - repo, branch, Dockerfile, port, health check, subdomain (requires confirmation) | | `delete_service` | Permanently delete a service and its data (requires confirmation) | | `deploy_service` | Trigger a deployment for a service | | `list_blueprints` | List the blueprints you can deploy, with their stack tags | | `list_github_owners` | List the GitHub accounts a blueprint can be forked into | | `deploy_blueprint` | Fork a blueprint template, create the project and services, and start the first deploy | | `get_deployment_status` | Get the current status of a deployment, including its dependency vulnerability scan results | | `list_vulnerabilities` | List the critical dependency vulnerabilities from the lockfile scan of each repo service's latest stable build, for the organization or one service | | `get_latest_build` | Get the latest deployment and build job status for a service environment (`stable` or `preview`) | | `get_build_logs` | Retrieve orchestration build logs for a deployment | | `get_build_logs_by_build_id` | Same as `get_build_logs` but takes a `buildJobId` directly | | `get_runtime_logs` | Retrieve historical runtime logs for any deployment (live or past) | | `get_deployment_metrics` | Summarize a deployment's CPU and memory usage (avg, p95, max vs limit, OOM kills) over 1h, 6h or 24h | | `get_resource_pool` | Show the organization's CPU/memory pool, free headroom, allocation steps and per-replica maximums | | `set_service_resources` | Change a service's per-replica CPU and memory allocation (requires confirmation) | | `list_linkable_keys` | List the env var keys a service exports for linking (e.g. database credentials) | | `get_env_vars` | Get env vars of a service's stable environment (manual values masked) | | `link_env_vars` | Link env vars from a source service (e.g. a database) into another service | | `unlink_env_vars` | Remove linked env vars from a service | | `write_manual_env_vars` | Create or update manual env vars on a service (asks you to confirm first - see below) | | `provision_postgres` | Provision a managed PostgreSQL database in a project | | `provision_redis` | Provision a managed Redis-compatible datastore (Dragonfly) in a project | | `provision_object_storage` | Provision an S3-compatible object storage bucket in a project | | `list_custom_domains` | List the custom domains on a service with their verification status | | `add_custom_domain` | Add a custom domain to a service and get the DNS record to configure | | `verify_custom_domain` | Re-run DNS verification for a pending custom domain | | `remove_custom_domain` | Remove a custom domain from a service (requires confirmation) | | `task_agent` | Start an agent session on a service and submit the first task (coder or research) | | `list_agent_models` | List the AI models selectable for agent sessions (pass an id as `modelId` to `task_agent`) | | `continue_agent_session` | Send a follow-up prompt, resume a parked session, or continue a closed session in a fresh sandbox | | `get_agent_run` | Poll a run for its result: reply, files changed, commit and PR link | | `get_agent_session` | Get a session's status, handoff brief, pending question and messages | | `list_agent_sessions` | List agent sessions in an organization or for one service | | `close_agent_session` | Permanently close a session and tear down its sandbox | | `publish_page` | Publish a static site (HTML/CSS/JS) to its own `.rock8cloud.page` address, password-protected by default | | `set_page_access` | Make a published page public, or protect it with a username and password, without republishing | | `list_pages` | List published pages with their public URLs | | `delete_page` | Delete a published page (files and listing entry) | ## Setup [#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 [#chatgpt] 1. Open [ChatGPT Plugins](https://chatgpt.com/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-code] ```bash claude mcp add rock8cloud --transport http https://app.rock8.cloud/mcp ``` Or add to your project's `.mcp.json`: ```json { "mcpServers": { "rock8cloud": { "type": "http", "url": "https://app.rock8.cloud/mcp" } } } ``` ### Pi [#pi] Pi requires an MCP extension. Install the [Pi MCP Adapter](https://www.npmjs.com/package/pi-mcp-adapter): ```bash pi install npm:pi-mcp-adapter ``` Add the server to your project's `.mcp.json`: ```json { "mcpServers": { "rock8cloud": { "url": "https://app.rock8.cloud/mcp", "auth": "oauth" } } } ``` Restart Pi, then authorize Rock8Cloud from inside Pi: ```text /mcp-auth rock8cloud ``` Complete the browser authorization flow. You can inspect the connection later with `/mcp`. ### Zed [#zed] Zed does not support remote HTTP MCP servers natively yet. Use [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a stdio bridge. Add to your project's `.zed/settings.json` (or global `~/.config/zed/settings.json`): ```json { "context_servers": { "rock8cloud": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.rock8.cloud/mcp"] } } } ``` ### OpenCode [#opencode] Add to your project's `opencode.json`: ```json { "mcp": { "rock8cloud": { "type": "remote", "url": "https://app.rock8.cloud/mcp" } } } ``` then run `opencode mcp auth` to authorize ### OpenAI Codex CLI [#openai-codex-cli] ```bash codex mcp add rock8cloud --url https://app.rock8.cloud/mcp ``` Or update your `~/.codex/config.toml`: ```toml [mcp_servers.rock8cloud] url = "https://app.rock8.cloud/mcp" ``` ### IntelliJ [#intellij] Open **Settings → Tools → AI Assistant → Model Context Protocol**, click **Add**, choose **STDIO**, and paste: ```json { "mcpServers": { "rock8cloud": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.rock8.cloud/mcp"] } } } ``` ### Troubleshooting [#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: ```bash 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 [#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 [#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](/docs/guides/develop-mode) 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 [#blueprint-deploy-workflow] A [blueprint](/docs/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](/docs/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 [#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 [#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 [#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 [#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](/docs/guides/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 [#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. | Tool | View | | ---------------------- | ------------------------------------------------------------------------------------------------------- | | `open_dashboard` | Every project and service in an organization with its live deployment state | | `open_service_panel` | A panel beside the conversation that tracks one service: live status, deployments and logs | | `show_service` | One service with its live state, recent deployments, build and runtime logs, and a redeploy action | | `show_usage` | CPU and memory graphs of a service over 1h, 6h or 24h, with its limits, deploys and out-of-memory kills | | `show_pages` | The organization's pages with their links, access and status | | `show_vulnerabilities` | The critical dependency vulnerabilities of every repo service, or of one service | ## Writing Environment Variables [#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 [#verify-connection] After setup, verify the MCP server is connected: **Claude Code:** ```bash 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.