Skip to main content

Connect Your AI Agent

CompactHive runs a remote MCP server (Model Context Protocol) at https://app.compacthive.io/mcp. It lets your own AI coding agent — Claude Code, Codex CLI, OpenCode, Cursor, VS Code, or any other MCP-capable client — see and act on your tenant directly, instead of you copy-pasting context back and forth.

This is separate from Hive Code (the in-portal browser agent covered earlier in this book). Hive Code is CompactHive's own agent, running server-side in your namespace. The MCP server is for your own agent, running wherever you already use it (your laptop, your CI, your editor). You can use either, both, or neither.

Connecting

In the portal, go to AI Agents (sidebar, or Settings → AI Agents tab). The page has copy-paste setup for Claude Code, Codex CLI, OpenCode, Cursor, and VS Code, with two ways to authenticate:

  • OAuth (recommended) — your agent opens a login/consent screen in the browser; no token to copy or store yourself. This is the quickest path for Claude Code, Codex CLI, and OpenCode.
  • Personal access token (PAT) — generate a token in Settings → AI Agents, paste it into your client's config. Use this for clients that don't support OAuth yet, or for scripted/CI use.

Shortest example (Claude Code):

claude mcp add --transport http compacthive https://app.compacthive.io/mcp
# then run /mcp inside Claude Code and choose "Authenticate"

Every token and connected app can be reviewed and revoked at any time from Settings → AI Agents.

Bring your own model credentials

Just like Hive Code, connecting the MCP server does not give your agent model access — you keep using whatever subscription or API key you already pay for (Claude Code's own Anthropic login, Codex's own OpenAI login, your own API keys, etc.). CompactHive only exposes your tenant's apps, services, and deploy pipeline as tools the agent can call; it is not a model provider.

What your agent can do

  • Read-only by default: list your apps and services, check app health and logs, see build status and recent deploys, check your usage against your tier's limits, and pull the same platform reference documentation (CI setup, Dockerfile conventions, deploy API) that's built into the portal's Developer Guide.
  • Operate (opt-in): tick "Operate" when connecting (PAT checkbox, or the OAuth consent screen) to let the agent take actions — restart or redeploy an app, set an app's environment variables or secrets, enable a service, create a new app, or scaffold a brand-new project end-to-end (create a repo, add a starter Dockerfile and CI pipeline, deploy it, and push the first build) on the built-in Forgejo provider. Every action-taking tool shows a preview of exactly what it's about to change before anything happens, unless your agent explicitly confirms it.
  • Every tool call is logged in your tenant's audit trail, and you can disconnect an agent at any time.

Limitations

  • GitHub repositories/sessions are not yet supported over MCP for project scaffolding — that tool works against the built-in Forgejo provider only. If your tenant is connected to GitHub (beta), connect and push manually via Settings → "Set Up" instead; see the Git Providers page for the current state of GitHub support.
  • There's no delete, no pod exec, no secret reads (you can set secrets, not read them back), and no deployment rollback — the same boundaries that apply in the portal UI apply here.
  • Model access, as above, is entirely bring-your-own.