# hubris-mcp [Health: Active]

**Category:** 🗣️ Conversational AI  
**Repository:** https://github.com/Aimagine-life/hubris-mcp  
**GitHub Stars:** 0  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hubris-mcp

## Description
OpenAI-compatible LLM gateway for Russia, billed in rubles — catalog, balance, chat via MCP.

## Tools
Capabilities this server exposes over MCP:

- **models_list** — Walk the whole Hubris catalogue page by page, ordered by model id. Returns every active model with its capabilities, context window and ruble price.

Use this when you need the complete catalogue — to cache it, to count models, or to scan for something no filter covers. When you are looking for a model that fits a task, use models_search instead: it filters by capability, price and context server-side and saves you a few hundred rows.

Paging: read `nextCursor` from the response and pass it back as `cursor`. When `nextCursor` is absent you have reached the end. The catalogue holds roughly 550 models, so a full walk is about 11 calls at the default page size.
- **models_search** — Find models that fit a task. Filters by name, the tool that runs the model, capability, price ceiling and context window, and can sort the result. This is the tool to reach for when choosing a model — it does the filtering server-side and returns at most 50 rows.

All filters combine with AND, and every one of them is optional: calling with no arguments returns the first 50 active models.

Two things worth knowing about prices. `maxInputPer1MRub` keeps only models billed per token, because a ruble-per-million ceiling is meaningless for a model billed per image. The `cheap_input` and `cheap_output` sorts push non-token models to the end of the list for the same reason — their token rate reads as zero, which would otherwise put video models at the top of "cheapest".
- **models_get_pricing** — The full price of one model in rubles — the authoritative answer to "what does this cost".

Prefer this over the pricing embedded in models_list and models_search whenever the model is not billed per token. Those two return "0.00" token rates for such models; only this tool returns `perUnit`, where the real price per image, per second or per thousand characters lives.

For speech models it also lists the voices speech_create accepts (`supportedVoices`), for video models the durations, resolutions and aspect ratios video_create accepts (`video`).

Errors with InvalidParams if the model id is unknown or the model is no longer active.
- **balance_get** — Current balance of the Hubris account the API key belongs to, in rubles.

Worth checking before a long or expensive run: requests are refused once the balance is spent. The balance can go slightly negative — one operation is allowed to overdraw it, and the next one is refused.

Two representations of the same number come back. Use `balanceKopecks` for arithmetic and comparisons — it is an exact integer string. Use `balanceRub` for display.
- **chat_complete** — Run a chat completion on any model in the Hubris catalogue and get the answer back. Full parity with POST /v1/chat/completions — same request shape, same response shape, including tool calls, structured output and reasoning. Streaming is not available here: MCP tool calls are synchronous, and `stream` is ignored if you pass it.

This is how you reach a model you cannot reach otherwise — pick an id with models_search, then call it here. Useful for delegating a subtask to a cheaper or a stronger model than the one you are running on.

Chat models that draw (Gemini Image, GPT-5 Image) take modalities ["image","text"]; their pictures come back as image content next to the JSON. Voice answers of audio models need streaming and are available through the HTTP API only.

The call spends real money from the account balance: it is billed per token at the catalogue price, in rubles. balance_get shows what is left.
- **embeddings_create** — Turn text into embedding vectors with any embedding model in the Hubris catalogue — for semantic search, RAG, deduplication and clustering. Same as POST /v1/embeddings, OpenAI shape: data[i].embedding is the vector for input[i].

Pass a list of strings to embed a batch in one call, which is faster and cheaper than one call per string. Vectors are long: 1536 numbers make about 30 KB of JSON, and the whole answer lands in your context. Embed only what you will actually store or compare, use `dimensions` where the model allows it, and send large batches through the HTTP API (POST /v1/embeddings).

Spends money from the account balance: billed per input token. usage.cost_rub is what this call cost.
- **rerank** — Order documents by how well they answer a query, best first, with a relevance score each. Same as POST /v1/rerank. Typical use: a vector or keyword search finds 50–100 candidates, rerank picks the few that really answer the question, and only those go to the model — answers get more accurate and prompts shorter.

results[].index points into the documents list you sent. Scores are comparable only within one response.

Spends money from the account balance: Cohere models are billed per search (up to 100 documents), the rest per input token. usage.cost_rub is what this call cost.
- **decisions_ask** — Ask a decision model (Jev, Clef, Mercury Decide and others) structured questions about some data and get probabilities instead of text. Same as POST /v1/decisions. Question types: "noul" — yes or no, answered as the probability of yes; "choice" — one option out of criteria; "score" — a level on the scale given in criteria. All questions are answered in one call.

Good for classification, routing and triage where you need a calibrated number rather than prose — and much cheaper than asking a chat model.

Spends money from the account balance: billed per input token only. usage.cost_rub is what this call cost.
- **image_generate** — Draw an image from a text description with an image model from the Hubris catalogue (FLUX, Recraft, Seedream, GPT Image and others) and get the picture back right away as image content. Same as POST /v1/images/generations.

Only models whose `tool` is "image_generate" work here. Models that draw inside a chat answer and also write text (Gemini Image, GPT-5 Image) have tool "chat_complete" and run there. Sizes such as 4K can be heavier than your client accepts in one answer — ask for 2K or less here.

Spends money from the account balance: most image models are billed per image, some per megapixel or per token — models_get_pricing shows the price before you call. The charge shows up in usage_get.
- **speech_create** — Read text aloud with a text-to-speech model from the Hubris catalogue and get the audio file back as audio content. Same as POST /v1/audio/speech.

Many models need a voice: the list of voices is on the model card (models_get_pricing → supportedVoices) — pick one from there. The answer is mp3 unless you ask for pcm. Up to 5 000 characters per call, a few minutes of speech; split longer texts or use the HTTP API (POST /v1/audio/speech).

Spends money from the account balance: priced per character of text or per second of audio, depending on the model — models_get_pricing shows which. The charge shows up in usage_get.
- **transcription_create** — Transcribe a recording to text with a speech recognition model from the Hubris catalogue (Whisper, GPT-4o Transcribe, Deepgram, ElevenLabs Scribe and others). Same as POST /v1/audio/transcriptions with the audio sent as base64.

Pass the file content itself, base64-encoded — links to files are not accepted. Every byte of the recording is written out inside this call, so it suits clips of seconds, not minutes; send longer recordings through the HTTP API (POST /v1/audio/transcriptions).

Spends money from the account balance: most models are billed per second or minute of audio, some per token. usage.cost_rub is what this call cost.
- **video_create** — Start generating a video from a text prompt with a video model from the Hubris catalogue (Veo, Kling, Seedance, Wan, Hailuo, Runway and others). Same as POST /v1/videos. Generation takes from one to several minutes, so this returns a task id right away; poll video_get with it every 15–30 seconds until status is "completed" or "failed".

Allowed durations, resolutions and aspect ratios differ per model — models_get_pricing lists them under `video`. This tool takes a text prompt only: starting from images or a source video, and models that need a source — video editing, upscaling and talking avatars (FLUX Video Edit, FLUX Video Upscale, Runway Aleph, HeyGen Avatar) — work through the HTTP API (POST /v1/videos).

Connected through OAuth (Claude, Cursor, VS Code)? Video needs the permission to create videos on the consent screen. If this tool answers that videos:write is missing, reconnect.

Spends money from the account balance: priced per second of video. The largest possible cost is held when the task starts, the actual cost is charged when it completes and the difference is returned; a failed generation returns the whole hold.
- **video_get** — Status of a video task started with video_create: "pending", "in_progress", "completed" or "failed". Same as GET /v1/videos/{id}.

While the video is being made, usage.estimated_cost is the amount held on the balance. Once it is "completed", usage.cost is the final price and the answer carries a link to the video file as an MCP resource (video/mp4) — read that resource to get the video itself. The file is kept for 72 hours. Files over 25 MB are not served as a resource; download those over HTTP (GET /v1/videos/{id}/content) with the same key.

Free to call: it only reads the task. Poll every 15–30 seconds, not more often.
- **youtube_transcribe** — Transcript or summary of a YouTube video by its link. Same as POST /v1/video/transcriptions. The video is checked before any model is called: a deleted, private or link-only video, a live stream and a video longer than four hours are refused without charge.

mode "exact" gives a word-for-word transcript, each line with an [HH:MM:SS] timecode, optionally labelled by speaker. mode "fast" gives a summary with key points and rough timecodes — several times faster and cheaper on long videos. An hour-long video in "exact" takes several minutes, which may exceed your client's tool timeout; prefer "fast" there.

Spends money from the account balance: billed per token of the model doing the work. usage.cost_rub is what this call cost.
- **usage_get** — What this connection has spent over a period: requests, tokens, cache savings and the total in rubles. Same as GET /v1/usage. With an API key that is the key's spending; connected through OAuth, it is the spending of the whole app connection over the period, not just of the current hourly token.

Use it to report what a run cost, to check spending against a budget, or to see the charge of tools that do not return their own price (image_generate, speech_create). balance_get shows what is left on the account.

Free to call: it only reads.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "hubris-mcp": {
    "command": "npx",
    "args": ["-y","hubris-mcp"],
    "env": {
      "HUBRIS_API_KEY": "",
      "HUBRIS_MCP_URL": ""
    }
  }
}
```

**Requires environment variables:** `HUBRIS_API_KEY`, `HUBRIS_MCP_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What hubris-mcp does

The hubris-mcp MCP server connects MCP clients to Hubris, an OpenAI-compatible gateway with ruble-denominated billing. It provides access to a catalog of active models and account information, then routes requests to models for text, embeddings, reranking, structured decisions, images, speech, transcription, and video.

The catalog tools support cursor-based listing, filtering by execution tool, capability, price, and context length, and retrieving model-specific pricing. Pricing details can include speech voices and video duration or resolution options. Account tools report the current balance and usage over a period, including request counts, tokens, and rubles spent.

## How it works

The hosted service is available at `https://api.hubris.pw/mcp` over Streamable HTTP. Clients authenticate tool calls with a Bearer API key. The local alternative is a Node.js stdio process that declares the same tool set and forwards calls to the hosted endpoint.

The hubris-mcp MCP server also exposes a model catalog resource at `hubris://catalog/models`, quickstart documentation at `hubris://docs/quickstart`, and a finished-video resource for hosted video results. A `compare-models {task}` prompt is included for comparing available models against a stated task.

## Setup and configuration

For a local installation, build the package with npm and start the compiled process:

```bash
npm install && npm run build
HUBRIS_API_KEY=sk-gw-... node dist/index.js
```

Docker is also supported. Pass `HUBRIS_API_KEY` into the container when starting it. The `HUBRIS_MCP_URL` variable can replace the default Hubris endpoint when the process must target another URL.

A hosted connection needs the Streamable HTTP URL and an `Authorization: Bearer sk-gw-...` header. Claude Desktop requires an `mcp-remote` shim because it only speaks stdio, while clients with Streamable HTTP support can connect directly. Create a dedicated Hubris key for MCP if you want to revoke it separately from other integrations; the key grants access to account balance information.

## Tools and capabilities

The hubris-mcp MCP server provides these operations:

- Discover active models, search catalog entries, and inspect pricing.
- Read the current balance and period-based usage totals.
- Send chat completion, embedding, reranking, and decision requests.
- Generate images, synthesize speech, transcribe base64-encoded audio, and start or inspect video jobs.
- Retrieve a transcript or summary for a YouTube video.

Video generation is asynchronous: `video_create` starts a job, and `video_get` checks its status and supplies download links when available. Generated images and speech are returned as MCP image or audio content.

## Limitations and notes

Listing the available tools does not require a credential, but calling them does. When `HUBRIS_API_KEY` is present, the stdio process obtains its tool list from the hosted endpoint; without the key, it uses the package’s bundled list, which may not include later additions.

The video content resource is available from the hosted endpoint only. Claude Desktop needs the remote transport shim, and other clients must support Streamable HTTP for a direct hosted connection. API usage can affect the Hubris account balance, so credentials should be handled as account-authorizing secrets.

_Full upstream README: https://allmcps.com/mcp/hubris-mcp/readme_