How to connect Algolia to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Algolia from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Algolia tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Algolia call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

Because this is a key integration, "connected" only means a key was accepted at setup. Check three things in order. First, key tier: a search-only key queries perfectly and fails on every write, which produces a connection that looks half-broken but is behaving exactly as Algolia intends — if the agent needs to write, the connected key needs write rights. Second, whether the key still exists: keys deleted or regenerated in Algolia fail on every call from that moment, and re-pasting the current one from the dashboard is the fix. Third, application scope — keys belong to a specific Algolia application, so an index that lives in a different application returns a permission-shaped error rather than a not-found, which is easy to misread as a broken integration.

Ask the agent to diagnose it:

Call algolia_get_authentication and tell me which Algolia application this key belongs to and what it is permitted to do. Then quote the exact error from the failed call. Do not retry it yet.

These look alike and have different fixes. If Hermes lists no Algolia tools whatsoever, pairing or the connection is incomplete: confirm the plugin was installed with --enable, that hermes clawlink begin and hermes clawlink finish both completed, and that Algolia shows as connected in the dashboard. If most tools work and one name fails, the name is wrong rather than missing and the error lists the closest real ones. There is also a timing case specific to this setup: tool schemas load on demand rather than shipping with the plugin, so the very first Algolia call in a fresh session can arrive before the catalog does and simply needs a retry. Note that the fix search results usually describe for this symptom — editing an MCP block in a client's config file — does not apply, because there is no local server here and no file to edit.

Ask the agent to diagnose it:

List the Algolia tools you actually have access to. If there are none, say so plainly. If there are, tell me which one browses an index and use that exact name.

Usually the index or the application rather than the query. Algolia keys are scoped to an application, and index names are exact, so a query against a name that differs by an environment prefix — the classic products versus products_prod — returns an empty result rather than an error. The second cause is that browsing and searching are different operations with different behaviour: algolia_browse_index walks the whole index and is what you want for auditing, while search applies relevance and filters and can legitimately return nothing for a narrow query. Have the agent confirm which application it is on and list what it can actually see before you go looking at the records themselves.

Ask the agent to diagnose it:

Tell me which Algolia application this key belongs to, then browse the index I named with algolia_browse_index and report how many records you can see and the exact index name you used.

Double-check that the API key for Algolia has the right scopes or account access. A valid key can still be too limited for some reads or writes.

Yes. ClawLink is the fastest way to connect Hermes to Algolia: link your Algolia account once in the browser and Hermes Agent can call the Algolia API through 127 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Algolia in the dashboard and Hermes can use it from the next message — no config files, and the Algolia key you paste is stored server-side instead of in your environment.

About two minutes. Sign in, click Connect next to Algolia in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Algolia working from chat.

It depends on what you want the agent to do, and this is the decision worth making deliberately rather than pasting whichever key was nearest. Algolia issues an Admin key that can do everything including managing indices and other keys, search-only keys that can query and nothing else, and scoped keys derived from those. If the agent's job is answering questions about search performance and running queries, a search-only key gives it exactly that and makes a destructive mistake impossible. If it needs to write records, update settings, or manage rules, it needs a key with those rights — and you should expect it to be able to use them. The key you paste is the ceiling on what the agent can do, which is a more reliable control than instructions in a prompt.

It is in a different place with different failure modes, and the honest comparison is worth making. A key in a .env or a shell profile lives on every machine you copied it to, survives in shell history and backups, and keeps working until someone remembers to rotate it. Here it is stored server-side and used when a tool call needs it, so it is not sitting on your laptop, and removing the connection from the ClawLink dashboard stops the agent using it immediately. Rotating in Algolia means updating one place rather than every machine and CI job that had it. What has not changed is that a key with write access can write — choose the tier accordingly.

Considerably more than search. It can add, replace, and clear records, browse an index, and find individual objects; read and change index configuration; export and manage rules and synonyms; run and read A/B tests; and pull the analytics that tell you whether search is working — click-through rate, conversion rate, average click position, no-result rate, and the actual no-results searches people ran. That last group is the underrated half: the questions worth asking an agent are usually about search quality rather than about fetching a record you could have fetched yourself.

Algolia ships its own MCP server, and if Algolia is the only thing your agent needs to touch, running it is a perfectly reasonable choice. The difference is scope and upkeep: their server is a process you run and point a client at, whereas this connection sits alongside every other account you have connected, with one pairing step for Hermes and one dashboard to revoke from. The workflows that benefit are the ones that cross products — reading no-results searches, then filing the gaps as issues somewhere else — because the agent already holds those other connections.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.