inferhive-mcp

MCP server for InferHive, the collaborative GPU lending and LLM inference platform by Impulsate. It lets an AI assistant (Claude Code, Claude Desktop or any MCP client) check your balance, list and rent GPUs, reserve them, stop instances, write your kubeconfig and call the OpenAI-compatible LLM gateway, all paid in processing coins (PC), the platform's credits.

It is built on the inferhive SDK and uses the same credentials. Requires Python 3.12+. The portal lives at https://inferhive.impulsate.lat.

Install and log in

pip install inferhive        # the SDK and CLI, used to log in
inferhive login --scope rent # approve in the browser; use --scope read to only look

inferhive login stores a platform key (pak_...) in ~/.config/pcoin/platform_key (mode 0600). The MCP server reads it from there; you do not need to install the server yourself if your client runs it with uvx.

Add it to your client

Claude Code:

claude mcp add inferhive -- uvx inferhive-mcp
# without a browser login: a pak_ key created in the portal (API keys)
claude mcp add inferhive -e INFERHIVE_API_KEY=pak_... -- uvx inferhive-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "inferhive": { "command": "uvx", "args": ["inferhive-mcp"] }
  }
}

inferhive-mcp speaks stdio. inferhive-mcp --http [--port N] serves streamable HTTP on 127.0.0.1 instead; it has no authentication of its own, so never expose it to a network. inferhive-mcp --version and --help print and exit without starting the server.

Tools

list_gpus shows nodes you can reserve for a time slot (reserve_gpu); list_offers shows what you can rent right now (rent_instance). Reservations and instances are different things: cancel_reservation / release_gpu act on reservations, stop_instance on instances. The portal caps both reservations and rentals at 4 hours.

Credentials

Resolved like the SDK, in this order:

1. Platform key pak_...: INFERHIVE_API_KEY, or ~/.config/pcoin/platform_key from inferhive login. Its scope is set at login: read only looks; rent can reserve, rent and spend PC. The key saved by inferhive login already has the rent scope; one created with --scope read makes every write tool fail with 403, and also get_kubeconfig: the portal requires rent for it even though it is a GET, because it hands out a credential. If the key expired or was revoked, run inferhive login again.
2. PCOIN_TOKEN: a Cloudflare Access session token (legacy browser session).
3. PCOIN_API_KEY or ~/.config/pcoin/api_key: an LLM key pck_..., used only by llm_chat. It is a different key from the platform key, and inferhive login does not create it. Before the first llm_chat: create it in the portal (https://inferhive.impulsate.lat/llm, LLM API) and save it with inferhive llm keys save. Without it the tool fails and tells you exactly that.

Create and revoke LLM keys in the portal (LLM API): no platform key can manage keys, so the server only lists them. PCOIN_CONFIG_DIR changes the configuration folder.

Safety

• Reserving and renting require confirm=true: the assistant should show you the cost and ask before passing it. Without it, nothing is written.
• cancel_reservation, release_gpu and stop_instance are marked as destructive; configure your client to ask for approval on them.
• rent_instance refuses community nodes unless accept_community=true: the owner of such a node is root on it and can see what runs there.
• Secrets are never logged or returned. Rental responses never include the app token (Jupyter, vLLM).
• get_kubeconfig only writes inside ~/.kube/ (even with overwrite=true); any other path is refused before contacting the portal.
• On HTTP 429 the server waits at most 10 s inside a tool call; longer Retry-After values are returned to the assistant ("El portal pide esperar N s") instead of blocking for minutes.
• For automation, use a pak_ key with the smallest scope (read if it only looks) and an expiry, and revoke it from the portal when done.

Changes

• 0.2.1: the server identifies itself as inferhive with its package version; --version and --help; get_kubeconfig only writes inside ~/.kube/ and explains the rent scope on 403; llm_chat documents the pck_ key and says how to get one when it is missing; 429 responses report the portal's Retry-After instead of sleeping for minutes; reserve_gpu caps hours at 4 like the portal; clearer descriptions for list_gpus/list_offers/release_gpu.
• 0.2.0: removes create_llm_key and revoke_llm_key, which a platform key can never use; manage LLM keys in the portal. 14 tools.
• 0.1.0: first release, with 16 tools.

License

MIT. See LICENSE.