Skip to main content
Hermai ships a dedicated MCP server package. Use it when your agent runtime supports local MCP tools and you want agents to look up schemas or submit missing-workflow requests without scraping pages or hand-writing API calls.

​
Install

Run the MCP server directly with npm:
Or install it globally:
Read-only catalog lookup and public schema request intake work anonymously within public rate limits. Authenticated requests use HERMAI_API_KEY or HERMAI_PLATFORM_KEY if you provide it in the MCP client environment. Providing a key also unlocks the fetch_schema execution tool, which runs hosted /v1/fetch and consumes credits.

​
Generic client config

MCP client config paths vary by runtime, but the server entry has this shape:
The environment variable is optional for public lookup and schema request intake.

​
Tools

​
lookup_schema

Search Hermai by domain, task, category, or verification state. Use this before scraping a website.

​
list_public_schemas

Browse public schemas with optional filters such as q, category, verified, sort, and limit.

​
fetch_schema

Execute a registered schema through hosted /v1/fetch and return live data. This tool is only exposed when HERMAI_API_KEY (or HERMAI_PLATFORM_KEY) is set, and it consumes Hermai credits: a standard call costs 1 credit, some higher cost sites cost 5, and only successful calls are billed. Resolve the exact site and endpoint with lookup_schema first, then call:
  • site — registered host, for example wegmans.com.
  • endpoint — endpoint name from the schema, for example product_search. Case-sensitive.
  • params — optional endpoint parameters as key/value pairs.
The result includes the upstream data plus a meta summary (credits_used, credits_remaining, latency_ms, cached); failed fetches surface the API code and message, plus upgrade_to and upgrade_url when the workspace is out of credits. Use it for read workflows only. Write and owner-approved workflows go through the Hermai CLI’s signed-write path. Set HERMAI_FETCH_TIMEOUT_MS to override the default 120s timeout.

​
submit_schema_request

Submit the six-field intake for a missing or brittle workflow:
  • domain
  • task
  • read_or_write
  • auth_shape
  • output_shape
  • failure_mode
Optional context fields include source_url, requester_agent, requester_contact, and idempotency_key. Never include cookies, API keys, bearer tokens, private session data, or credentials in a schema request.

​
classify_browser_workflow

Locally classify prose as direct_api, hidden_endpoint, browser_only, needs_owner, or needs_more_fields. Use this to decide whether to look up an existing schema, submit a request, or ask the user for more intake fields.

​
check_schema_request_status

Check a previously submitted schema request by id.

​
When to use MCP

Use MCP when the agent runtime can run local tool servers. Use the direct HTTP API when the runtime cannot run MCP. Use CLI commands directly when you need terminal-oriented flows such as browser cookie import, session bootstrap, or signed write execution.