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.

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.

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.

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 ***.

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.