# How to connect Algolia to Hermes Agent (paste one key, 127 tools)

> Connect Algolia to Hermes with ClawLink: paste your Algolia key once and 127 tools work from chat. No MCP server to run, nothing stored on your machine.

Web version: https://claw-link.dev/hermes/algolia

Most guides for giving Hermes Agent Algolia access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Algolia setup: pair once in the browser and your always-on Hermes agent can act on Algolia for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Algolia.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Algolia** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect algolia  # connect Algolia (browser OAuth)
npx -y @useclawlink/cli actions algolia  # list available actions
npx -y @useclawlink/cli run algolia <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Algolia in the [ClawLink dashboard](https://claw-link.dev/dashboard) — paste your Algolia API key once.

Verify the connection by asking Hermes:

> Use algolia_get_no_results_searches and algolia_get_no_results_rate for the index \<index> over the last 30 days. Show me the top queries that returned nothing and group them into themes.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Algolia is connected in the dashboard, that agent calls the same 127 Algolia tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Algolia MCP for Hermes

Looking for a Algolia MCP server for Hermes Agent? ClawLink connects Algolia to Hermes Agent and exposes 127 Algolia tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Algolia integration](https://claw-link.dev/openclaw/algolia) works the same way.

This is Hermes Agent, the MCP-native runtime from Nous Research — not HashiCorp's Forge Hermes, which search engines confuse it with constantly. Algolia authenticates with API keys, so the honest pitch is not that keys disappear; it is that you handle one, once, in a browser. You paste an Algolia key into the hosted setup page, ClawLink holds it server-side, and Hermes can call the 127 Algolia tools below from chat. What you skip is the part that usually goes wrong: no key in an environment file, no MCP server of your own to run and keep updated, no `config.yaml` to edit, and one place to revoke when someone leaves.

## What the Hermes Agent Algolia integration can do

127 Algolia tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 127.

### 30 of 127 Algolia tools for Hermes

| Tool | What it does |
|---|---|
| **Add AB test** `algolia_add_ab_test` | Create an A/B test comparing search performance between two index variants |
| **Add or replace record** `algolia_add_or_replace_record` | Add or replace a specific record in an index by objectID |
| **Add record** `algolia_add_record` | Add a record to an index with auto-generated objectID |
| **Browse index** `algolia_browse_index` | Retrieve all records from an index |
| **Clear objects** `algolia_clear_objects` | Clear records of an index without affecting settings |
| **Export rules** `algolia_export_rules` | Export all rules defined on an index |
| **Find object** `algolia_find_object` | Find the first object matching a query or filter in an index |
| **Get AB test** `algolia_get_ab_test` | Retrieve detailed information about an A/B test by its ID |
| **Get add to cart rate** `algolia_get_add_to_cart_rate` | Retrieve add-to-cart rate metrics for e-commerce search analytics |
| **Get API key** `algolia_get_api_key` | Retrieve the permissions and details of a specific API key |
| **Get app task** `algolia_get_app_task` | Check the status of an application task |
| **Get authentication** `algolia_get_authentication` | Retrieve an authentication resource by its ID |
| **Get average click position** `algolia_get_average_click_position` | Retrieve average click position metrics from Algolia Analytics |
| **Get click positions** `algolia_get_click_positions` | Retrieve the distribution of clicks by position from Algolia Analytics |
| **Get click through rate** `algolia_get_click_through_rate` | Retrieve click-through rate (CTR) for searches with at least one click event |
| **Get config** `algolia_get_config` | Retrieve a Query Suggestions configuration by index name |
| **Get config2** `algolia_get_config2` | Retrieve the advanced personalization configuration |
| **Get conversion rate** `algolia_get_conversion_rate` | Retrieve conversion rate for searches with conversion events |
| **Get destination** `algolia_get_destination` | Retrieve a destination by its ID |
| **Get dictionary languages** `algolia_get_dictionary_languages` | List available languages for dictionary entries |
| **Get dictionary settings** `algolia_get_dictionary_settings` | Retrieve dictionary settings for all dictionaries |
| **Get logs** `algolia_get_logs` | Retrieve log entries for API requests made to your Algolia application |
| **Get no click rate** `algolia_get_no_click_rate` | Retrieve the rate of searches that received no clicks |
| **Get no results rate** `algolia_get_no_results_rate` | Retrieve the fraction of searches that didn't return any results |
| **Get no results searches** `algolia_get_no_results_searches` | Retrieve the most frequent searches that produced zero results |
| **Get object position** `algolia_get_object_position` | Retrieve an object’s position in a result set |
| **Get objects** `algolia_get_objects` | Retrieve multiple records from an index |
| **Get purchase rate** `algolia_get_purchase_rate` | Retrieve purchase rate metrics for searches that led to purchase events |
| **Get recommend rule** `algolia_get_recommend_rule` | Retrieve a Recommend rule that was previously created in the Algolia dashboard |
| **Get recommend task status** `algolia_get_recommend_task_status` | Check the status of a Recommend task |

## Example prompts

**Find what search is failing at**

> Use algolia_get_no_results_searches and algolia_get_no_results_rate for the index \<index> over the last 30 days. Show me the top queries that returned nothing and group them into themes.

**Check search quality**

> Pull algolia_get_click_through_rate, algolia_get_conversion_rate, and algolia_get_average_click_position for \<index> over the last two weeks and tell me whether relevance is getting better or worse.

**Inspect a record before changing it**

> Use algolia_find_object to show me the record with objectID \<id> in \<index>. Do not modify anything yet — I want to see the current fields.

**Review an A/B test**

> List the A/B tests on \<index>, then use algolia_get_ab_test on the most recent one and tell me whether it reached significance and which variant won.

## How the Algolia tools behave

The details that decide whether a prompt returns data, writes something, or quietly does neither.

- **The connected key's tier is the real permission boundary.** A search-only key reads and never writes, whatever the prompt asks for. Choose the tier to match the job rather than relying on instructions.
- **Keys are scoped to one Algolia application.** An index in another application is invisible, and the error reads like a permission problem rather than a missing index.
- **Index names are exact.** Environment suffixes like `_prod` or `_staging` are the usual reason a browse returns nothing.
- **Browse and search are different operations.** `algolia_browse_index` walks everything and suits audits; search applies relevance and filters and can correctly return nothing.
- **The analytics tools are the high-value half.** `algolia_get_no_results_searches`, `algolia_get_no_click_rate`, `algolia_get_conversion_rate` and friends answer questions about search quality that a record fetch cannot.
- **`algolia_clear_objects` empties an index.** It is the most destructive tool here and should never be reachable from an open-ended cleanup instruction.

## ClawLink vs. building it yourself

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.

| | Manual | ClawLink |
|---|---|---|
| **Credential handling** | Collect, validate, store, and rotate the Algolia API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected Algolia account becomes available to the agent without you building credential management. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Algolia. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Algolia actions to the runtime in a format your agent can reliably use. | 127 tools for Algolia are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Algolia to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Algolia in the browser, and the 127 tools above work from chat. There is no SDK and no config file, and the Algolia key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Algolia
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`.

### Connection succeeds but no tools appear
Reconnect Algolia from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Algolia tools
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.

### Algolia returns 403 or "permission denied" on one action while others work
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.

### Algolia returns 403 or an invalid-API-key error although the connection shows as connected
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:

```text
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.
```

### Algolia tools are not found, or no Algolia tools appear in Hermes at all
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:

```text
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.
```

### A search or browse returns nothing although records exist in the dashboard
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:

```text
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.
```

### API key setup works but results look incomplete
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.

### Is there a Hermes Agent Algolia integration?
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.

### How do I connect Algolia to Hermes with ClawLink?
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.

### How long does it take to connect Algolia to Hermes Agent?
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.

### Why use ClawLink instead of wiring Algolia up myself?
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.

### Which Algolia key should I connect?
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.

### Is my key safer here than in an environment file?
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.

### What can the agent actually do with Algolia?
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.

### How is this different from Algolia's own MCP server?
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.

### Hermes paired but still can't use Algolia
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`.

## Related

- [GitHub](https://claw-link.dev/hermes/github) — Manage repositories, issues, pull requests, and workflows
- [PagerDuty](https://claw-link.dev/hermes/pagerduty) — Manage incidents, on-call schedules, and services
- [Hermes SafetyCulture integration](https://claw-link.dev/hermes/safetyculture) — SafetyCulture (formerly iAuditor) is a workplace operations platform that enables teams to conduct digital inspections, manage audits, track issues, schedule tasks, and maintain compliance through mobile and web applications.