Use the API from AI assistants

The Hippomundo Enterprise MCP server lets an AI assistant that supports the Model Context Protocol (MCP) call this API. It is published on npm as @hippomundo/enterprise-mcp under the MIT license. Your assistant starts it on your own machine and talks to it over standard input and output; nothing is hosted for you. Every tool call becomes an ordinary API request with your API key in the apikey header.

Point the server at the sandbox while you build and test. The sandbox serves fictional horses, riders and competitions at production prices, paid with free play credits: each workspace starts every UTC day with 50,000, the previous day's remainder expires, and play credits cannot be bought. It needs no payment details and is rate limited. Create an account at https://sandbox.enterprise.hippomundo.com/register, create an API key in its portal, and set both variables in your assistant's configuration below:

HIPPOMUNDO_API_KEY=<your sandbox key>
HIPPOMUNDO_API_BASE_URL=https://sandbox.enterprise.hippomundo.com/api

Sandbox keys work only on the sandbox. For real data, create a key in your Customer portal at https://enterprise.hippomundo.com and remove HIPPOMUNDO_API_BASE_URL.

Each API operation is one tool, named after its operation ID, for example searchHorses, listClassResults or readBreedingPedigree. Tool descriptions, parameters and ordinary result schemas come from the public OpenAPI document shipped with each release. getUsage returns your current usage. The server gives your assistant short instructions: find IDs with a search or the free lists, then read results or pedigrees, and check each tool's description for its cost. The Sandbox guide lists a demo request for every tool.

From version 0.1.3, getEntitlementFilteredOpenAPI returns a compact catalog under response: charged: false, full_schema_uri and operations. Each operation has operation_id, method, path, summary and schema_uri. Ask your assistant to read an MCP resource only when it needs a schema:

• hippomundo://schema/openapi returns the full OpenAPI document for the operations your key may use.
• hippomundo://schema/operations/<operationId> returns a standalone OpenAPI document for one operation, with its referenced definitions and security schemes. For example, use hippomundo://schema/operations/searchHorses.

The catalog call, resource listing and every valid resource read each fetch current access from the API and cost no credits. There is no local access cache. An unknown or restricted operation returns the same resource-not-found error. API failures return a protocol error with sanitized error data and charged: false, without falling back to a schema shipped with the server. The HTTP endpoint GET /v1/openapi.json still returns the full filtered document. Tool listing still includes the result schemas shipped with the release; compact discovery does not remove all context costs.

Names, descriptions, schema text and other returned strings are untrusted data. They are never instructions for the assistant to follow.

You need Node.js 22 or later, which provides npx, and an API key. Your assistant starts the server with npx -y @hippomundo/enterprise-mcp@0.2.0, which downloads it on first use; there is nothing else to install. The server reads these environment variables:

• HIPPOMUNDO_API_KEY: your API key. Without a key the server does not start, and it never prints the key.
• HIPPOMUNDO_API_KEY_FILE: instead of HIPPOMUNDO_API_KEY, the full path of a file that holds your key on one line. Setting both stops the server, and so does a file that cannot be read or is empty.
• HIPPOMUNDO_API_BASE_URL (optional): defaults to https://enterprise.hippomundo.com/api. Set it to https://sandbox.enterprise.hippomundo.com/api with a sandbox key. If it is set but empty, the server does not start.
• HIPPOMUNDO_API_ALLOW_CUSTOM_HOST (optional): set it to 1 to send your key to a host that is neither a Hippomundo API address nor a local development address. Any other value stops the server.

The server sends your key only to a Hippomundo API address (enterprise.hippomundo.com, sandbox.enterprise.hippomundo.com or staging.enterprise.hippomundo.com, over https), to a local development address, or to another https host you allow with HIPPOMUNDO_API_ALLOW_CUSTOM_HOST=1. Local development addresses are localhost, loopback addresses, private network addresses (RFC 1918 and IPv6 unique local), Tailscale addresses (100.64.0.0/10), and names ending in .localhost, .local or .ts.net; they also accept plain http. The server does not follow redirects, so your key is sent only to that base URL. Requests carry the User-Agent header hippomundo-enterprise-mcp/<version>.

In bash or zsh, run these lines. The first waits for you to paste your key and press Enter. It does not show the key, and it replaces ~/.hippomundo-api-key with a new file that holds the key and that only you can read. The key appears neither on screen, nor in your shell history, nor in the command line of a running program:

(umask 077 && read -rs key && rm -f ~/.hippomundo-api-key && printf '%s\n' "$key" > ~/.hippomundo-api-key)
claude mcp add hippomundo --env "HIPPOMUNDO_API_KEY_FILE=$HOME/.hippomundo-api-key" -- npx -y @hippomundo/enterprise-mcp@0.2.0

For the sandbox, also pass --env 'HIPPOMUNDO_API_BASE_URL=https://sandbox.enterprise.hippomundo.com/api' before the --. Claude Code saves the path of the key file, not the key, in ~/.claude.json, for you only and for the current project.

Open Settings, then Developer, and choose Edit Config. It opens claude_desktop_config.json, in ~/Library/Application Support/Claude/ on macOS and in %APPDATA%\Claude\ on Windows. Add this entry and restart Claude Desktop:

{
  "mcpServers": {
    "hippomundo": {
      "command": "npx",
      "args": ["-y", "@hippomundo/enterprise-mcp@0.2.0"],
      "env": {
        "HIPPOMUNDO_API_KEY": "<your key>",
        "HIPPOMUNDO_API_BASE_URL": "https://sandbox.enterprise.hippomundo.com/api"
      }
    }
  }
}

This example uses the sandbox. For real data, use a key from your Customer portal, and remove the HIPPOMUNDO_API_BASE_URL line and the comma at the end of the line before it.

Add the same mcpServers entry as for Claude Desktop to ~/.cursor/mcp.json, which applies to all your projects. A project's own .cursor/mcp.json also works, but it then holds your key, so keep that file out of source control.

Add this to ~/.codex/config.toml, which the Codex CLI and its IDE extension read:

[mcp_servers.hippomundo]
command = "npx"
args = ["-y", "@hippomundo/enterprise-mcp@0.2.0"]

[mcp_servers.hippomundo.env]
HIPPOMUNDO_API_KEY = "<your key>"
HIPPOMUNDO_API_BASE_URL = "https://sandbox.enterprise.hippomundo.com/api"

This example uses the sandbox. For real data, use a key from your Customer portal and remove the HIPPOMUNDO_API_BASE_URL line.

These commands pin version 0.2.0, so restarting your assistant keeps the same server version. To upgrade, read the changelog, change the version in your assistant's configuration and restart it. Test the new version against the sandbox before using a production key.

Give the API key your assistant uses a credit cap per UTC day or month on the key's page in the portal. A loop or an unexpected instruction then cannot spend more than the cap: requests beyond it fail with api_key_credit_cap_reached, cost nothing, and the result tells the assistant when the next period starts.

With HIPPOMUNDO_API_KEY, your assistant's configuration holds your API key in plain text. Keep that file private and out of source control, and do not paste the key into a conversation with the assistant. With HIPPOMUNDO_API_KEY_FILE, as in the Claude Code lines above, the configuration holds only the path of the key file. In the Claude Desktop, Cursor and Codex configuration, you can replace the HIPPOMUNDO_API_KEY entry with HIPPOMUNDO_API_KEY_FILE and the full path of a file that holds your key, such as the one the Claude Code lines create. Create a separate key for each assistant or machine, so that you can revoke one in your Customer portal without affecting your other integrations.

Each tool call is an ordinary API request: it costs the same credits as that request, and errors are never charged. From version 0.1.6, the getEntitlementFilteredOpenAPI catalog shows each operation's current price in its credits field, as the API reports it: credits_text for people and milli_credits to compare with your balance. Your assistant decides which tools to call, so build and test on the sandbox before you use a production key. Tools for billable operations send an Idempotency-Key, and the server reuses it when it retries a lost connection, a rate limit or a retryable server error, so those retries are never charged twice. To repeat a call yourself without a second charge, pass the same Idempotency-Key argument again within 24 hours.

A successful call returns the response with its request_id and, from version 0.1.1, rate_limit_remaining: the requests left in the current rate-limit window, when the API reports it. From version 0.2.0, it also returns charged_milli_credits, the milli-credits the API debited for that request, and idempotent_replayed: true when the API answered a repeat of an earlier request with the same Idempotency-Key without charging it again. A failed call returns a tool error with the stable code, the HTTP status, the request_id, retryable and charged. When the outcome of a billable call is unknown, charged is null and the error includes idempotency_key. Repeat the call with that value as the Idempotency-Key argument. A successful response larger than 8 MiB returns outcome_unknown for a billable call and response_too_large for a free one. A result too large for one MCP message returns result_too_large with what the call was charged. Neither is retried; ask for less, for example with a smaller page_size or narrower filters. Quote the request_id when you contact support, and use getUsage to check your spending. Invalid arguments and malformed forwarded headers return invalid_arguments with charged: false before the API receives a request. A well-formed unsupported Hippomundo-Version value still reaches the API, which returns unsupported_version.