Agents and MCP
Hive Runner has an MCP server. Point Claude Code, Cursor, Codex or any MCP client at one URL and it can read your hive, write the workflow change and tell you what a month would cost.
https://hiveworkr.thecomputerplumbers.com/mcpThere is no API key to paste. The client registers itself and you sign in with GitHub in a browser.
From nothing to a first job
Each state you can be in, who acts, and how the agent can tell. An agent does everything except four things only a person can: install the GitHub App, run the install command on a machine, add funds and approve the connection.
| State | Who | Do | How the agent sees it |
|---|---|---|---|
| Not connected | agent | Add the MCP server: claude mcp add --transport http --scope user hiverunner https://hiveworkr.thecomputerplumbers.com/mcp, or the same URL in any MCP client. The client opens a browser. | 401 from /mcp |
| Not signed in | person | Sign in with GitHub. There is nothing else to set up. | the browser |
| Not in a hive | person | Install Hive Runner on a GitHub organization you own, at https://hiveworkr.thecomputerplumbers.com/install. Someone who is not an owner requests it and waits for an owner; a personal account cannot be a hive. The consent page continues when you come back. | the consent page says so; the connection fails until then |
| Choosing a hive | person | Pick the hive and allow the permissions. | tokens arrive |
| No machine | person | On an Apple Silicon Mac or a Linux machine with KVM, run curl -fsSL https://get.hiveworkr.thecomputerplumbers.com/install.sh | sh, then sign in with GitHub in the browser that opens. Any member of the organization can. | get_hive.nextSteps, machines.total === 0 |
| Machine but none connected | person | Run hived run, or open the machine's lid. | jobs.blockedBy === "no-machine-online" |
| No job yet | agent | Edit the workflow to runs-on: hive: call get_workflow, commit, push. | lifetime.jobs === 0 |
| Balance out or budget spent | person | Add funds at the wallet URL get_hive returns, or raise the budget (set_budget). | jobs.blockedBy |
| Running | agent | Watch it with list_jobs, get_job and get_usage. |
What an agent can do
- Say whether a job can start right now and, if not, what is in the way: no machine online, an empty balance, a spent budget.
- Write the workflow change, with a fallback runner for when no machine is free.
- Read machines, jobs, signed receipts, usage and what you have saved against GitHub-hosted runners.
- Compare prices for your volume before you move anything.
- With your approval as an owner: change hive settings, set a monthly budget and remove machines.
An agent cannot add funds or a card. Payments are made by a person in the browser.
Connect
Claude Code
claude mcp add --transport http --scope user hiverunner https://hiveworkr.thecomputerplumbers.com/mcpThen run /mcp in a session, or claude mcp login hiverunner, to sign in. --scope user makes it available in every project.
Claude Desktop and claude.ai
Open Settings, then Connectors, then Add custom connector. Paste the URL above and choose Register automatically.
Cursor
{
"mcpServers": {
"hiverunner": {
"url": "https://hiveworkr.thecomputerplumbers.com/mcp"
}
}
}Codex CLI
codex mcp add hiverunner --url https://hiveworkr.thecomputerplumbers.com/mcp
codex mcp login hiverunnerOther clients
Add an HTTP (Streamable HTTP) MCP server at the URL above. The client needs OAuth with dynamic client registration and PKCE, which is what the MCP specification asks for.
Signing in
- Your browser opens and you sign in with GitHub.
- You pick one hive. The connection can reach that hive and no other.
- You see the permissions the client asked for, and allow or deny them.
You need to be in a hive first. If your organization has not installed Hive Runner, start with the Quickstart.
Tools
An agent should call get_hive first. It answers most questions on its own and lists what to do next.
| Tool | What it does | Permission | Who |
|---|---|---|---|
get_hive | Everything about the connected hive in one call: who you are in it (`you`: role, your machines, what you can change), balance, whether a job can start now and what blocks it, machines, labels and prices, budget, settings, lifetime savings, and nextSteps to act on. Call this first. | hive:read | Member |
get_current_user | The person this connection acts as and their role in the hive. get_hive's `you` says which machines are theirs and what they can change. | hive:read | Member |
list_machines | Every machine serving the hive: owner, cores, architecture, presence, daemon version and recent work. Use it when get_hive says no machine is online, or before remove_machine. | hive:read | Member |
list_jobs | Recent jobs, newest first, with result, duration and price. Filter by status or repository; call get_job for one job's receipt. | hive:read | Member |
get_job | One job by id, with its price split and the signed receipt once it has finished. Ids come from list_jobs. | hive:read | Member |
get_usage | The last fourteen days by day: jobs, failures, minutes, what was spent and what the same minutes list for on GitHub-hosted runners, plus the daily balance. | hive:read | Member |
get_leaderboard | Who and which machines carried the hive's jobs over the last week, month or all time. | hive:read | Member |
get_pricing | The per-minute price of every label beside GitHub-hosted and Blacksmith list prices. Pass minutes to compare a month. Use it to answer what moving a workflow would save. | hive:read | Member |
get_workflow | The workflow YAML that runs a job on the hive, with a fallback runner for when no machine is free. Use it when editing a repository's .github/workflows files. | hive:read | Member |
update_settings | Change who may add machines (allowedTeams), who is paid (earningsDestination), whether macOS jobs run, or how jobs are routed. Only what you pass changes. Pass the version from get_hive to refuse saving over someone else's change. | hive:write | Owner |
set_budget | Set, change or remove the hive's monthly budget for jobs, and whether reaching it warns or pauses new jobs. Pass monthlyUsd: null to remove it. | hive:write | Admin or owner |
set_auto_top_up | Turn automatic top-up on or off, or change the amount, the balance it acts below and its monthly limit. It charges the card saved by a payment made in the browser; a card cannot be added here. | hive:write | Admin or owner |
remove_machine | Stop a machine serving this hive. It keeps serving its other hives, and its owner can add it back with `hived link`. Ids come from list_machines. | hive:write | Machine owner or hive owner |
Permissions
hive:readreads the hive you picked: machines, jobs, balance, settings and receipts. Any member can grant it.hive:writechanges settings, the budget, automatic top-up and machines. Only an owner or admin can grant it, and a client has to ask for it.
Every request is checked against your membership as it is now. If you leave the organization on GitHub, the connection stops working.
Revoke a connection
Agents in the console lists every connection you have approved. Revoking one stops it at once, including tokens already issued.
llms.txt
/llms.txt is a plain-text summary of Hive Runner for a model to read: what it is, the price, the MCP endpoint and the one-line workflow change (runs-on: hive).
Next: Labels and sizes