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,in the sidebar for client snippets, or Settings → AIAgent Agentsaccess tab).to Thecreate pagea hastoken. copy-pasteThere setup for Claude Code, Codex CLI, OpenCode, Cursor, and VS Code, withare two ways to authenticate:

  • One CompactHive access token for MCP + Git — generate it once in Settings → Agent access, configure your MCP client, then run the Git credential-helper snippet shown there once. Use this for the full code → push → deploy workflow.
OAuth (recommended)recommended for MCP-only clients) — your agent opens a login/consent screen in the browser;screen; 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 supportcopy. OAuth yet,cannot orauthenticate for scripted/CI use.Git.

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 → AIAgent Agents.access. Revoking a PAT removes both MCP and Git access (Git caches expire within 3 seconds).

One token: configure once, then clone and push

    Create a token with Read + deploy + push code access in Settings → Agent access. Copy it now: it is shown once. Paste it into your MCP client's local secret/config, never a committed file or agent chat. Run the Git setup snippet from the same screen once. It uses your real tenant Git host and the SAME token. For illustration only (replace placeholders locally): 
    git config --global credential.https://<workspace>-forgejo.compacthive.dev.helper store
printf 'protocol=https\nhost=<workspace>-forgejo.compacthive.dev\nusername=compacthive\npassword=<YOUR_COMPACTHIVE_TOKEN>\n\n' | git credential approve

    The store helper saves credentials unencrypted on disk. Linux/macOS can use it; macOS users can replace store with osxkeychain for Keychain. On Windows, Git Credential Manager prompts once; use manager instead of store. Keep secrets out of shell history and shared terminals. Any non-empty Git username works; we recommend compacthive.

      Ask the agent to call setup_project for your repo, review the preview and confirm. It returns the clone URL; wait for CI setup with get_project_status before your first push. Clone the unchanged URL (git clone https://<workspace>-forgejo.compacthive.dev/<owner>/<repo>.git), edit, commit and push. CI builds and deploys automatically; inspect status and health with MCP.

      Read access includes MCP read tools and Git clone/fetch for writable members, but no push. Read + deploy + push code adds MCP operate tools and git:write. Push-code permission covers every repository accessible to you in this account. Readonly members have no Git access. Existing tokens do not silently gain push permission: create a new push-code token if needed. For repository-scoped CI, manual Forgejo tokens remain under Settings → Git access (Advanced / CI).

      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): tickchoose "Operate"Read when+ connectingdeploy (PAT+ checkbox,push code for a PAT, or Operate on the OAuth consent screen)screen, to let the agent take actions — restart or restart/redeploy an app,apps, set an app's environment variables orand write-only secrets, enable aservices service,or createset up 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 theForgejo. built-inTools Forgejopreview provider. Every action-taking tool shows a preview of exactly what it's about to changechanges before anythingapplying happens,with unlessexplicit yourconfirm. agentOAuth explicitlyoperate confirmsaccess it.still does not grant Git authentication.
      • 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.