Metadata-Version: 2.5
Name: inferhive-mcp
Version: 0.2.1
Summary: MCP server for InferHive: let an AI assistant check your balance, rent and reserve GPUs and call the LLM gateway, paid in processing coins
Project-URL: Homepage, https://hive.impulsate.lat
Project-URL: Portal, https://inferhive.impulsate.lat
Project-URL: Documentation, https://hive.impulsate.lat/detailed
Project-URL: SDK on PyPI, https://pypi.org/project/inferhive/
Author-email: David Petrocelli <dmpetrocelli@gmail.com>, Agustín Hernando <agusher1304@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,gpu,inferhive,llm,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: inferhive>=0.3.0
Requires-Dist: mcp<2,>=1.2
Description-Content-Type: text/markdown

# inferhive-mcp

[MCP](https://modelcontextprotocol.io) server for [InferHive](https://hive.impulsate.lat), 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`](https://pypi.org/project/inferhive/) SDK and uses the same
credentials. Requires Python 3.12+. The portal lives at https://inferhive.impulsate.lat.

## Install and log in

```bash
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:

```bash
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`):

```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

| Tool | What it does |
|---|---|
| `get_balance` | Available, locked and total PC |
| `get_history(limit)` | Latest ledger movements |
| `list_gpus` | Nodes with GPU model, VRAM, PC/hour rate and availability |
| `list_offers(gpu, max_price, min_vram, tier)` | What you can rent right now (GPU nodes and the `cpu` pool) |
| `list_reservations` | Your reservations |
| `reserve_gpu(node, start_iso, hours, confirm)` | `confirm=false` (default) only shows the cost; `confirm=true` reserves and locks PC |
| `cancel_reservation(id)` | Cancels before it starts; refunds everything |
| `release_gpu(id)` | Ends a running **reservation** early (not an instance: use `stop_instance`); refunds the unused hours |
| `rent_instance(offer, template, hours, accept_community, image, model, confirm)` | `confirm=false` (default) is a preview; `confirm=true` rents and starts the instance |
| `list_instances` | Your instances: state, node, template, time left, PC spent and URL |
| `stop_instance(id)` | Stops an instance (its `/scratch` is lost); you pay only the time used |
| `get_kubeconfig(path, overwrite)` | Writes your kubeconfig (0600, default `~/.kube/pcoin-config`, always inside `~/.kube/`); never returns its content. Needs the `rent` scope |
| `llm_chat(prompt, model, max_tokens)` | Calls the LLM gateway; returns the text, token usage and PC cost. Needs an LLM key `pck_` (see below) |
| `list_llm_keys` | Your LLM keys (prefix only) |

`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`.
