Skip to main content

Connect Hermes Agent to Speech is Cheap

This guide walks you through connecting Hermes Agent to the Speech is Cheap MCP server, so Hermes can transcribe audio and video recordings from public URLs and from files on its own computer. Hermes sends your API key in a request header, so there is no sign-in page.

What You Need​

Before starting, ensure you have:

  • An installation of Hermes Agent: Hermes Agent is a self-hosted AI agent from Nous Research. MCP support ships with the standard installation. See the Hermes Agent MCP documentation for background on how Hermes handles MCP servers.
  • A Speech is Cheap account with an active plan: Pick a plan on the Pricing page if you do not have an account. Your initial API key arrives by email.
  • A Speech is Cheap API key: Keys start with sk_. Create a dedicated API key in the Dashboard named "Hermes Agent" so you can revoke it on its own. The dashboard displays keys only once. See the Dashboard guide for details.

Setup Steps​

Follow these steps to configure Hermes Agent with the Speech is Cheap MCP server:

  1. Add your API key to ~/.hermes/.env:

    SIC_API_KEY=sk_...

    The variable name must be SIC_API_KEY. The upload command returned by the prepare_upload tool reads $SIC_API_KEY, and Hermes passes that variable to the commands it runs.

    Hermes has a built-in CLI command, hermes mcp add <name> --url ... --auth header, but it saves the key under MCP_SPEECHISCHEAP_API_KEY, which the upload command cannot read. Editing ~/.hermes/.env and ~/.hermes/config.yaml directly ensures both tools and uploads use the same key.

  2. Add the server definition to ~/.hermes/config.yaml:

    mcp_servers:
      speechischeap:
        url: https://mcp.speechischeap.com/mcp
        headers:
          Authorization: Bearer ${SIC_API_KEY}

    If mcp_servers: already exists in config.yaml, add speechischeap: under it. Hermes fills ${VAR} placeholders in headers from environment variables, including ~/.hermes/.env, when connecting to the server. This keeps your API key out of config.yaml.

  3. Test the MCP server connection in your terminal:

    hermes mcp test speechischeap

    Hermes connects and lists five tools: transcribe, get_transcript, cancel_job, prepare_upload, and check_access.

    This command confirms network connectivity and tool discovery. It does not validate the API key: the server accepts any key at connection time and checks it only when a tool runs. A prompt or a call to check_access verifies the key.

  4. Apply the configuration to your Hermes session:

    • If you run the Hermes gateway (hermes gateway) for messaging apps, the gateway watches config.yaml and connects newly added MCP servers within about a minute, without a restart.
    • If you have an active chat session, it keeps its current tool set. Run /reload-mcp inside the session, or start a new session with /new, to load the Speech is Cheap tools.

If Hermes Uses the Codex Runtime​

If your Hermes setup routes model calls through Codex (model.openai_runtime: codex_app_server in ~/.hermes/config.yaml), Codex connects to MCP servers directly using ~/.codex/config.toml.

In this mode, two issues arise:

  • Running hermes codex-runtime migrate copies Hermes MCP servers into a managed block in ~/.codex/config.toml and writes the header with your API key filled in as plain text.
  • Hermes declines Codex's tool-approval prompts for external MCP servers. As a result, Codex rejects transcribe with user rejected MCP tool call (while read-only tools such as check_access succeed).

To resolve both issues, add the server entry manually to ~/.codex/config.toml after the line # end hermes-agent managed section:

[mcp_servers.speechischeap]
url = "https://mcp.speechischeap.com/mcp"
bearer_token_env_var = "SIC_API_KEY"
default_tools_approval_mode = "approve"

Declaring the server outside the managed section prevents hermes codex-runtime migrate from overwriting it or writing your API key to disk in plain text. The default_tools_approval_mode = "approve" setting allows Codex to execute Speech is Cheap tools without prompting, including transcribe, which starts a billable job.

Test the Connection​

Start a session with Hermes Agent and test the integration with a sample recording:

Please transcribe this audio file using Speech is Cheap: https://cdn.speechischeap.com/podcast-sic-api-01.m4a

Hermes calls the Speech is Cheap MCP server to transcribe the audio and prints the resulting text. In our end-to-end test, this 20-minute audio sample returned the full transcript in a single call.

You can also test transcribing a local audio file:

Please transcribe /path/to/recording.mp3 using Speech is Cheap.

For local files, Hermes calls prepare_upload, runs the returned upload command in its terminal using $SIC_API_KEY, and retrieves the transcript with get_transcript. Transcribing local files requires Hermes to have permission to run terminal commands on the computer where the file is stored.

Troubleshooting​

If you encounter issues during setup or while transcribing, check these common error messages:

  • Speech is Cheap rejected the API key. (in a conversation) The API key is invalid or has been revoked. Generate a new key in the Dashboard, update SIC_API_KEY in ~/.hermes/.env, and run /reload-mcp in your session. Note that hermes mcp test speechischeap does not validate your key; it checks only that the server is reachable and lists its tools.
  • This API key has no active plan… (in a conversation) Your API key is recognized, but the account lacks an active subscription or billing method. Open the Dashboard and update your plan under the Billing section.
  • user rejected MCP tool call If Hermes runs through the Codex runtime (model.openai_runtime: codex_app_server), Hermes declines tool approvals from Codex for external MCP servers. Add [mcp_servers.speechischeap] to ~/.codex/config.toml with default_tools_approval_mode = "approve" as described in If Hermes Uses the Codex Runtime.
  • URL download errors When transcribing from a URL, the audio or video file must reside at a publicly accessible URL that downloads directly without requiring a login, session cookies, or interactive screens. See Input Requirements for supported media formats and URL rules.
  • Try again shortly messages These messages indicate temporary service or connection interruptions. Wait a few moments and resubmit your prompt.
  • Failed jobs If a transcription job fails, you are not charged. Only completed jobs bill against your account.

Disconnecting​

To disconnect Speech is Cheap from Hermes Agent:

  • Remove the speechischeap entry from ~/.hermes/config.yaml. If you configured the Codex runtime, also remove the [mcp_servers.speechischeap] entry from ~/.codex/config.toml. A running Hermes gateway drops a removed server entry within about a minute.
  • To cut off access everywhere at once, revoke the key in the Dashboard. Revocation can take a minute or more to apply across all systems.

ClawHub Skill​

Hermes can also transcribe with the Speech is Cheap Transcribe skill (asr), published by speechischeap on ClawHub. Instead of MCP tools, the skill gives Hermes instructions and a helper script that it runs with Bash, and the script calls Speech is Cheap with curl. It transcribes audio and video from public URLs and local files. In our test, Hermes transcribed an 11-second local audio file through the skill and returned the transcript and job ID.

Install it in your terminal:

hermes skills install clawhub/asr

Hermes scans the skill and asks you to confirm before it installs it in ~/.hermes/skills/asr. Add --yes to skip the prompt. The scan rates the skill safe, with two MEDIUM supply_chain findings on its pnpm install --frozen-lockfile line. Only wallet mode runs that command, to install its dependencies.

The skill reads SIC_API_KEY, which Hermes passes from ~/.hermes/.env to the commands it runs. If you completed step 1, the skill needs no further setup. It also works with the Codex runtime and needs no entry in ~/.codex/config.toml, because it runs in the terminal rather than through MCP.

The skill also has a wallet mode, which pays per job in USDC on Base with no Speech is Cheap account or API key, up to a price ceiling you approve. It needs Node.js 22 or newer, pnpm, and an existing wallet. See the skill's README to set it up.

To remove the skill, run hermes skills uninstall asr.

Related Pages​