MCP server

Heimdallm serves a Model Context Protocol server, so an agent can use the marketplace as a set of tools: find and compare models by measured health and price, run chat, embeddings and media generation, store files, submit batches, read its own spend, manage keys and operate a provider listing.

Every tool call is an ordinary request to the public API made with the key the server is configured with. It is authenticated, rate limited, routed and billed exactly as the same request sent directly, and it appears in activity like any other. Discovery tools need no key and cost nothing.

The same tool set is served two ways:

The hosted server is at https://api-staging.heimdallm.com/api/mcp and needs no installation. The stdio server can also read and write local files: it uploads a file from a path, transcribes a local recording, and saves generated images, audio, video and meshes where the agent names.

Connect over HTTP#

Send the API key as Authorization: Bearer. Without one, the discovery tools answer and every account tool answers 401. In Claude Code:

claude mcp add --transport http heimdallm https://api-staging.heimdallm.com/api/mcp \
--header "Authorization: Bearer $HEIMDALL_API_KEY"

A client configured with JSON takes the same address and header:

{
"mcpServers": {
  "heimdallm": {
    "url": "https://api-staging.heimdallm.com/api/mcp",
    "headers": { "Authorization": "Bearer sk-hd-v1-…" }
  }
}
}

The hosted server is stateless: it opens no session and holds no stream, and GET on the address answers 405.

Run it locally#

Install and connect the CLI, then register heimdall-staging mcp as a command. It uses the key stored by heimdall-staging login, or HEIMDALL_STAGING_API_KEY when set. In Claude Code:

claude mcp add heimdallm -- heimdall-staging mcp

In Codex, ~/.codex/config.toml:

[mcp_servers.heimdallm]
command = "heimdall-staging"
args = ["mcp"]

Paths the tools read and write resolve against the directory the agent starts the server in. --management-key, or HEIMDALL_STAGING_MANAGEMENT_KEY, supplies a management key sent only on the key administration tools, so one server can hold both kinds of key. The CLI reference lists every flag.

Tools#

Discovery, public and free: search_models narrows the catalogue by text, modality, declared parameter (tools, structured_outputs, reasoning_effort), price, context, provider and zero-data retention. get_model compares the endpoints serving one model: provider, quantization, limits, prices, capability qualification and measured uptime, time to first token, throughput and tool-call success. get_model_health returns hourly health and benchmark scores. list_media_models, list_families, list_providers, list_zdr_endpoints, list_benchmarks and marketplace_status cover the rest of the catalogue.

Inference, billed: chat, complete, count_tokens, decide, embed and rerank. chat takes a model or a fallback list, provider routing preferences, tools, response_format and reasoning_effort, and returns the reply with its generation id, the provider that served it and the cost.

Media, billed: generate_image and synthesize_speech return the image or audio itself; transcribe_audio returns the transcript. submit_video and submit_mesh start a job that get_job polls and download_job_content fetches once it completes, and stop_mesh_refinement keeps a mesh as generated.

Files and batches: upload_file, list_files, get_file, delete_file and, locally, download_file. A stored file is named in a chat message by its id for 48 hours. create_batch, list_batches, get_batch and cancel_batch run many requests within 24 hours, each charged at most once.

Account: account_overview (the key's limit and usage beside the credit balance), get_activity, get_generation, list_my_models and deposit_options. No tool moves money: deposits are made in the dashboard or with the CLI.

Keys, with a management key: list_keys, get_key, create_key, update_key and revoke_key. A created key appears once in the answer and never again.

Providers, with a key on a provider's account: provider_status, provider_pull_now, provider_probe_now, provider_earnings and provider_statements. validate_models_document checks a models document against the marketplace's own parser offline and needs no key.

The server also offers three resources an agent can attach as context: the whole catalogue (heimdallm://catalogue), one model with its endpoints (heimdallm://models/{author}/{slug}) and the OpenAPI document (heimdallm://openapi).

Results and refusals#

Prices are USD per unit as decimal strings, exactly as the API publishes them. A measured figure that is null was not measured or is under its sample gate; it is never zero. A tool the API refuses answers with the status, the API's own message and the request id, so 401 (no key), 402 (insufficient credit), 403 (the wrong kind of key) and 429 (rate limited, with retry_after) each read as what they are. Tools return whole results: streaming is the API's own, and a tool result arrives once the request completes.