How to connect SerpApi 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 SerpApi from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

SerpApi 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 SerpApi 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.

This card used to carry Composio-generic causes that do not exist on this provider: SerpApi has no workspaces, and account access is not a thing a hosted connection can misconfigure. The real semantics, from SerpApi's own error documentation, are: 401 means the key itself is invalid, 403 means the account behind the key was deleted, suspended, or revoked, and 429 is a quota problem that SerpApi can surface with a permissions-shaped message. The classic 403 cause is a wrong provider's key: a Serper or SerpWow key pasted where a SerpApi key belongs authenticates to a different service and fails with 403. So the order is: confirm the pasted key is a real SerpApi key, then check the account's status on serpapi.com, then check the hourly window before assuming anything about the connection.

Ask the agent to diagnose it:

Call serpapi_get_search_archive with the most recent search id if one exists, and quote the exact error code and message from the failed call. Do not retry it yet.

On this provider a 429 can arrive worded as a permissions error, so before touching the connection, check the hourly window: SerpApi limits by searches per hour per plan (200 on Starter, 1,000 on Developer, 3,000 on Production, 6,000 on Big Data), and an agent that refines a query by re-searching is exactly the shape that exhausts it. The Account API exposes this_hour_searches, so the agent can report where it stands rather than guess. The fix is pacing, not reconnecting: wait for the window to roll, batch the queries you actually need, and tell the agent to search once per refinement step.

Ask the agent to diagnose it:

Tell me how many SerpApi searches you have made in the last hour and what you were researching. Quote the exact error text. Do not call SerpApi again until I reply.

Two failures share this symptom. If no SerpApi tools appear at all, the connection or pairing is incomplete: confirm the plugin was installed with --enable, that hermes clawlink begin and hermes clawlink finish both ran, and that SerpApi 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 first-call timing case: schemas load on demand, so the opening SerpApi call in a fresh session can arrive before the catalog and needs one retry. The checklist search results teach for this symptom, a malformed MCP URL or a key inside an mcpServers path, belongs to the manual setup and does not apply here.

Ask the agent to diagnose it:

List the SerpApi tools you actually have access to. If there are none, say so plainly and tell me whether SerpApi shows as connected. Do not guess tool names.

Double-check that the API key for SerpApi 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 SerpApi: link your SerpApi account once in the browser and Hermes Agent can call the SerpApi API through 48 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 SerpApi in the dashboard and Hermes can use it from the next message — no config files, and the SerpApi key you paste is stored server-side instead of in your environment.

About two minutes. Sign in, click Connect next to SerpApi 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 SerpApi working from chat.

Same underlying API, different setup and surface. SerpApi's plugin exposes a small set of search paths (web, maps, news, shopping) and their MCP server is registered with hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_KEY/mcp, with the key inside that URL and the config on your machine. This page's route stores the key server-side, exposes 48 named tools, and requires no MCP registration at all. If you already run the official plugin and it covers what you need, it is the simplest possible answer. If you want the wider surface and one place to manage and revoke the key, this is it.

Search engines well past Google: Google search and its specialized surfaces (images, maps, hotels, jobs, patents, shopping-adjacent, scholar, finance, events, forums), Bing, DuckDuckGo, Baidu, Naver, eBay, and more, plus search archive retrieval and location discovery. Every call is a real search under your key, which means the hourly allowance of your plan is the operating budget.

The risk framing search results give is key exposure, runaway cost loops, and prompt injection from web results, and all three are worth taking literally. The key here is stored server-side and never pasted into chat, so the exposure surface is the hosted connection rather than every machine that runs the agent. The cost shape is different from most providers: SerpApi bills by plan allowance rather than per-result units, so an agent that loops searches can exhaust the hourly window rather than the wallet. Web results are untrusted text by nature, so the agent should treat extracted page content as data, not as instructions. Those three guardrails, one dashboard revoke, and least-privilege prompts are the whole safety story.

The allowance scales with plan. SerpApi's documented hourly search limits are 200 per hour on Starter, 1,000 on Developer, 3,000 on Production, and 6,000 on Big Data, and the Account API reports live usage via account_rate_limit_per_hour and this_hour_searches. The agent can read its own position against the window, which is the correct first call in a long research session.

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.