nanocoai/nanoclaw / .claude/skills/add-tavily-tool
add-tavily-tool
VerifiedAdd Tavily Search and Extract as keyless remote MCP tools for selected NanoClaw agent groups. Use when installing Tavily web search or URL extraction without an API key.
Add Tavily Tool
Install the pinned mcp-remote bridge in the agent image and register Tavily's
remote MCP server for each selected agent group. The MCP server supplies its
tool descriptions and input schemas at runtime.
The registered server exposes:
mcp__tavily__tavily_searchmcp__tavily__tavily_extract
The registration is provider-agnostic: any provider with MCP support picks it
up (Claude, OpenCode, and Codex all do). Groups on the Claude provider already
have the built-in WebSearch and WebFetch tools
(container/agent-runner/src/providers/claude.ts), so the skill adds the most
for groups on other providers, and for Tavily's structured extraction
anywhere.
Phase 1: Pre-flight
Check whether the bridge is already in the image manifest, then list the groups:
grep -n '"mcp-remote"' container/cli-tools.json || true
ncl groups list
Ask which agent groups should receive Tavily. If mcp-remote is already
present at a pinned version, reuse the existing entry instead of adding a
second one.
Phase 2: Install the MCP bridge
Add this object to the top-level array in container/cli-tools.json when an
entry named mcp-remote is not already present:
{
"name": "mcp-remote",
"version": "0.1.38"
}
Keep the JSON valid and limit the entry to the two fields shown; this package does not require a native build-script opt-in.
Copy the dependency guard into the host test tree:
cp .claude/skills/add-tavily-tool/tavily-manifest.test.ts src/tavily-manifest.test.ts
Build the image and run the guard:
./container/build.sh
pnpm exec vitest run src/tavily-manifest.test.ts
The manifest is the only source-backed integration point. Per-group MCP
registration is runtime state stored through ncl, so it has no in-tree line
for a registration test to guard.
Phase 3: Register Tavily
config add-mcp-server and groups restart are approval-gated. Run from
inside a container they return approval-pending immediately; that is not an
error. Wait for the admin's approval and the follow-up system message before
moving on to Phase 4.
For each selected <group-id>, register one server named tavily:
ncl groups config add-mcp-server \
--id <group-id> \
--name tavily \
--command mcp-remote \
--args '["https://mcp.tavily.com/mcp/","--transport","http-only","--enable-proxy","--header","X-Tavily-Access-Mode:keyless","--header","X-Client-Name:nanoclaw","--ignore-tool","tavily_crawl","--ignore-tool","tavily_map","--ignore-tool","tavily_research"]' \
--env '{}'
The keyless header enables Tavily's IP-based allowance. The client-name header attributes calls to NanoClaw. The tool filters leave only Search and Extract available.
Restart each selected group:
ncl groups restart \
--id <group-id> \
--message "Tavily Search and Extract are installed. Run one Tavily search with max_results 1 and report whether it succeeds."
Phase 4: Verify
Confirm the stored configuration contains one tavily server with both
headers:
ncl groups config get --id <group-id>
Then check the selected agent's test response. The call must use
mcp__tavily__tavily_search. Tavily Crawl, Map, and Research must not appear in
the Tavily namespace.
Phase 5: Install the upgrade path
The keyless allowance is shared by every group on the host, so it can run out. Install standing instructions so the agent offers the paid-key upgrade at that moment instead of dead-ending. The upgrade has the user save a key that is then attached to the group through OneCLI agent grants; on an older gateway a saved key would reach every agent. So check the gateway and CLI first. It reads only:
sh .claude/skills/add-onecli/scripts/check-grants-gateway.sh /add-tavily-tool
If it fails, show the operator the message, skip this phase and keep the keyless
setup. Also remove an earlier <!-- tavily-upgrade:start --> to
<!-- tavily-upgrade:end --> block from each selected group's
groups/<group-folder>/instructions.prepend.md, so the agent does not ask anyone
to save a key, and restart each group you removed it from (ncl groups restart --id <group-id>): a running agent keeps the old block until it restarts. Install the
upgrade path once the gateway is upgraded. Otherwise, for each
selected group:
-
Resolve the OneCLI dashboard URL the user's browser can reach:
docker inspect onecli --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^APP_URL='If the value is a loopback or container-bridge address (
127.0.0.1,172.17.0.1,host.docker.internal), ask the operator which URL they open the OneCLI dashboard at, suggestinghttp://127.0.0.1:10254as the default. A public or tailnetAPP_URLneeds no question. -
Gate the deeplink:
curl -fs <dashboard-url>/connections/custommust return HTTP 200. If it does not (older OneCLI without the prefill route), replace step 2 of the template with: "Ask an operator to run, on the host:onecli secrets create --name tavily --type generic --host-pattern mcp.tavily.com --header-name Authorization --value-format 'Bearer {value}' --file <key-file>". -
Substitute
{{ONECLI_DASHBOARD_URL}}and{{AGENT_GROUP_ID}}in upgrade-instructions.md with the resolved URL and the group's id, and write the block intogroups/<group-folder>/instructions.prepend.md: replace an existing<!-- tavily-upgrade:start -->to<!-- tavily-upgrade:end -->block in place, append otherwise. Do not write intogroups/<group-folder>/CLAUDE.md; it is regenerated at spawn and appended blocks are lost. -
Have the operator open the composed deeplink once and confirm the create dialog loads with host
mcp.tavily.comprefilled. If they supplied a public URL whileAPP_URLwas a loopback address, suggest setting the public URL in the OneCLI dashboard (Settings, Instance) so future links stay stable. -
Restart each selected group:
ncl groups restart --id <group-id>.
Keyless limit
If Tavily returns HTTP 429 or monthly_cap_reached_bonus_eligible, the
keyless allowance is exhausted. With Phase 5 installed the agent offers the
upgrade on its own: the user creates a free API key and stores it through the
prefilled dashboard link; the key lands in the OneCLI vault. On OneCLI 1.44+ a
new key reaches no agent until it is attached, so the user then attaches it to
the group on the host (onecli agents grants attach-secret, a one-liner in the
upgrade block), and the gateway injects it into the bridge's requests. The agent then re-registers the server
without the X-Tavily-Access-Mode:keyless header and restarts the group. The
agent never sees the key.
Troubleshooting
command not found: mcp-remote: rebuild the image, then restart the group.- Tavily tools are absent: verify the group has a
tavilyMCP entry, then restart it. - Crawl, Map, or Research appears: restore all three
--ignore-toolpairs. 429ormonthly_cap_reached_bonus_eligible: the keyless allowance is exhausted; see Keyless limit for the OneCLI upgrade path.- The agent reports exhaustion but never offers the upgrade: check that
groups/<group-folder>/instructions.prepend.mdcontains thetavily-upgradeblock (Phase 5) and restart the group. A session that already discussed the limit keeps reasoning from that history;/clearstarts a clean one.
Removal
See REMOVE.md for the idempotent removal procedure.
References
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |