Metadata-Version: 2.5
Name: inferhive-mcp
Version: 0.1.0
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.

## 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)` | Releases a running reservation; 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`); never returns its content |
| `llm_chat(prompt, model, max_tokens)` | Calls the LLM gateway; returns the text, token usage and PC cost |
| `list_llm_keys` | Your LLM keys (prefix only) |
| `create_llm_key(name, confirm)` | Creates an LLM key; needs a browser session (see below) |
| `revoke_llm_key(id)` | Revokes an LLM key; needs a browser session (see below) |

## 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. If it 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`.
   Create it in the portal (LLM API) and save it with `inferhive llm keys save`.

No key can create or revoke keys: `create_llm_key` and `revoke_llm_key` only work with
`PCOIN_TOKEN`. With a `pak_` key, manage LLM keys in the portal instead.
`PCOIN_CONFIG_DIR` changes the configuration folder.

## Safety

- Reserving, renting and creating keys require `confirm=true`: the assistant should show you
  the cost and ask before passing it. Without it, nothing is written.
- `cancel_reservation`, `release_gpu`, `stop_instance` and `revoke_llm_key` 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, except the new key shown once by `create_llm_key`.
  Rental responses never include the app token (Jupyter, vLLM).
- 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.1.0: first release, with the 16 tools above.

## License

MIT. See `LICENSE`.
