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 in the sidebar for client snippets, or Settings → Agent access to create a token. There are 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 for MCP-only clients) — your agent opens a login/consent screen; no token to copy. OAuth cannot authenticate 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 from Settings → Agent access. Revoking a PAT removes both MCP and Git access (Git caches expire within 3 seconds).

One token: configure once, then clone and push

1. Create a token with Read + deploy + push code access in Settings → Agent access. Copy it now: it is shown once.
2. Paste it into your MCP client's local secret/config, never a committed file or agent chat.
3. 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.

4. 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.
5. 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): choose Read + deploy + push code for a PAT, or Operate on the OAuth consent screen, to let the agent restart/redeploy apps, set environment variables and write-only secrets, enable services or set up a project on Forgejo. Tools preview changes before applying with explicit confirm. OAuth operate access 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.