Hermai Mcp

Hermai MCP

Dedicated Model Context Protocol server for Hermai.

Use this package when an agent runtime supports MCP and should call Hermai as native tools. The Hermai CLI is a separate human/operator tool and is not required for MCP.

Install

Run directly with npx:

npx -y hermai-mcp

Or install globally:

npm install -g hermai-mcp
hermai-mcp

MCP Client Config

{
  "mcpServers": {
    "hermai": {
      "command": "npx",
      "args": ["-y", "hermai-mcp"]
    }
  }
}

Optional environment variables:

• HERMAI_API_BASE or HERMAI_PLATFORM_URL: API base URL. Defaults to https://api.hermai.ai.
• HERMAI_API_KEY or HERMAI_PLATFORM_KEY: API key for authenticated Hermai APIs. Public schema lookup and schema-request intake work without a key. Setting a key also unlocks the fetch_schema execution tool (see below).
• HERMAI_FETCH_TIMEOUT_MS: request timeout for fetch_schema. Defaults to 120000 (hosted fetch lanes can run tens of seconds).

Claude Code workflow

Use the local MCP server when you want Claude Code to discover a schema, inspect the available workflow, and make an authenticated read request. Hermai MCP is a local stdio server. It is not a remote Claude connector.

Install Claude Code, then add Hermai to your personal Claude Code configuration:

export HERMAI_API_KEY='hm_sk_...'
claude mcp add --scope user hermai -e HERMAI_API_KEY="$HERMAI_API_KEY" -- npx -y hermai-mcp
unset HERMAI_API_KEY

The key is saved in your local Claude Code configuration. Do not put this command in a repository, shared shell history, or a project scoped MCP configuration.

Confirm that Claude Code can see the server:

claude mcp list

Then start Claude Code and use this two step request:

Use lookup_schema to find a verified public Hermai schema for [the source and task].
Before making a fetch, show me the site, endpoint, required parameters, and whether
the result can be retrieved with fetch_schema.

After you approve the selected workflow:

Use fetch_schema with the site, endpoint, and parameters we selected. Return a short
summary of the records, then show credits_used, credits_remaining, and cached from
the response metadata.

lookup_schema is safe to use without a key. fetch_schema appears only when the key is configured. It reads data through Hermai Cloud and consumes credits for a successful request. Do not give the server browser cookies, bearer tokens, or a request that changes data on another service.

For a full verification checklist and the expected failure paths, see the Claude Code guide.

Tools

Always available (no key required):

• lookup_schema — search Hermai schemas by domain, task, category, or verification state.
• list_public_schemas — page through public schemas.
• submit_schema_request — submit the six-field intake for a brittle browser/API workflow.
• classify_browser_workflow — locally classify whether a workflow maps to direct API, hidden endpoint, browser-only, or owner/auth work.
• check_schema_request_status — check a schema request status.

Available only when HERMAI_API_KEY (or HERMAI_PLATFORM_KEY) is set:

• fetch_schema — execute a registered schema through hosted /v1/fetch and return live data. Read-only data retrieval, and it consumes Hermai credits: a standard call costs 1 credit and some higher cost sites cost 5; only successful calls are billed. Inputs: site, endpoint (resolve both with lookup_schema first; endpoint is case-sensitive), and optional params. The result includes the upstream data plus a meta summary (credits_used, credits_remaining, latency_ms, cached); failures surface the API code and message, plus upgrade_to and upgrade_url when a credit 402 offers an upgrade path. Use it for read workflows only — write/owner-approved workflows go through the Hermai CLI's signed-write path, not this tool.

Never submit cookies, bearer tokens, API keys, session IDs, or private session data through schema-request intake.