{"id":"add-tavily-tool","name":"add-tavily-tool","summary":"選択されたNanoClawエージェントグループに対して、Tavily Search and ExtractをキーレスリモートMCPツールとして追加します。","body":"# Add Tavily Tool\n\nInstall the pinned `mcp-remote` bridge in the agent image and register Tavily's\nremote MCP server for each selected agent group. The MCP server supplies its\ntool descriptions and input schemas at runtime.\n\nThe registered server exposes:\n\n- `mcp__tavily__tavily_search`\n- `mcp__tavily__tavily_extract`\n\nThe registration is provider-agnostic: any provider with MCP support picks it\nup (Claude, OpenCode, and Codex all do). Groups on the Claude provider already\nhave the built-in `WebSearch` and `WebFetch` tools\n(`container/agent-runner/src/providers/claude.ts`), so the skill adds the most\nfor groups on other providers, and for Tavily's structured extraction\nanywhere.\n\n## Phase 1: Pre-flight\n\nCheck whether the bridge is already in the image manifest, then list the groups:\n\n```bash\ngrep -n '\"mcp-remote\"' container/cli-tools.json || true\nncl groups list\n```\n\nAsk which agent groups should receive Tavily. If `mcp-remote` is already\npresent at a pinned version, reuse the existing entry instead of adding a\nsecond one.\n\n## Phase 2: Install the MCP bridge\n\nAdd this object to the top-level array in `container/cli-tools.json` when an\nentry named `mcp-remote` is not already present:\n\n```json\n{\n  \"name\": \"mcp-remote\",\n  \"version\": \"0.1.38\"\n}\n```\n\nKeep the JSON valid and limit the entry to the two fields shown; this package\ndoes not require a native build-script opt-in.\n\nCopy the dependency guard into the host test tree:\n\n```bash\ncp .claude/skills/add-tavily-tool/tavily-manifest.test.ts src/tavily-manifest.test.ts\n```\n\nBuild the image and run the guard:\n\n```bash\n./container/build.sh\npnpm exec vitest run src/tavily-manifest.test.ts\n```\n\nThe manifest is the only source-backed integration point. Per-group MCP\nregistration is runtime state stored through `ncl`, so it has no in-tree line\nfor a registration test to guard.\n\n## Phase 3: Register Tavily\n\n`config add-mcp-server` and `groups restart` are approval-gated. Run from\ninside a container they return `approval-pending` immediately; that is not an\nerror. Wait for the admin's approval and the follow-up system message before\nmoving on to Phase 4.\n\nFor each selected `<group-id>`, register one server named `tavily`:\n\n```bash\nncl groups config add-mcp-server \\\n  --id <group-id> \\\n  --name tavily \\\n  --command mcp-remote \\\n  --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\"]' \\\n  --env '{}'\n```\n\nThe keyless header enables Tavily's IP-based allowance. The client-name header\nattributes calls to NanoClaw. The tool filters leave only Search and Extract\navailable.\n\nRestart each selected group:\n\n```bash\nncl groups restart \\\n  --id <group-id> \\\n  --message \"Tavily Search and Extract are installed. Run one Tavily search with max_results 1 and report whether it succeeds.\"\n```\n\n## Phase 4: Verify\n\nConfirm the stored configuration contains one `tavily` server with both\nheaders:\n\n```bash\nncl groups config get --id <group-id>\n```\n\nThen check the selected agent's test response. The call must use\n`mcp__tavily__tavily_search`. Tavily Crawl, Map, and Research must not appear in\nthe Tavily namespace.\n\n## Phase 5: Install the upgrade path\n\nThe keyless allowance is shared by every group on the host, so it can run out.\nInstall standing instructions so the agent offers the paid-key upgrade at that\nmoment instead of dead-ending. For each selected group:\n\n1. Resolve the OneCLI dashboard URL the user's browser can reach:\n\n   ```bash\n   docker inspect onecli --format '{{range .Config.Env}}{{println .}}{{end}}' | grep '^APP_URL='\n   ```\n\n   If the value is a loopback or container-bridge address (`127.0.0.1`,\n   `172.17.0.1`, `host.docker.internal`), ask the operator which URL they open\n   the OneCLI dashboard at, suggesting `http://127.0.0.1:10254` as the default.\n   A public or tailnet `APP_URL` needs no question.\n2. Gate the deeplink: `curl -fs <dashboard-url>/connections/custom` must return\n   HTTP 200. If it does not (older OneCLI without the prefill route), replace\n   step 2 of the template with: \"Ask an operator to run, on the host:\n   `onecli secrets create --name tavily --type generic --host-pattern\n   mcp.tavily.com --header-name Authorization --value-format 'Bearer {value}'\n   --file <key-file>`\".\n3. Substitute `{{ONECLI_DASHBOARD_URL}}` in\n   [upgrade-instructions.md](upgrade-instructions.md) with the resolved URL and\n   write the block into `groups/<group-folder>/instructions.prepend.md`:\n   replace an existing `<!-- tavily-upgrade:start -->` to\n   `<!-- tavily-upgrade:end -->` block in place, append otherwise. Do not write\n   into `groups/<group-folder>/CLAUDE.md`; it is regenerated at spawn and\n   appended blocks are lost.\n4. Have the operator open the composed deeplink once and confirm the create\n   dialog loads with host `mcp.tavily.com` prefilled. If they supplied a public\n   URL while `APP_URL` was a loopback address, suggest setting the public URL in\n   the OneCLI dashboard (Settings, Instance) so future links stay stable.\n5. Restart each selected group: `ncl groups restart --id <group-id>`.\n\n## Keyless limit\n\nIf Tavily returns HTTP `429` or `monthly_cap_reached_bonus_eligible`, the\nkeyless allowance is exhausted. With Phase 5 installed the agent offers the\nupgrade on its own: the user creates a free API key and stores it through the\nprefilled dashboard link; the key lands in the OneCLI vault and the gateway\ninjects it into the bridge's requests. The agent then re-registers the server\nwithout the `X-Tavily-Access-Mode:keyless` header and restarts the group. The\nagent never sees the key.\n\n## Troubleshooting\n\n- `command not found: mcp-remote`: rebuild the image, then restart the group.\n- Tavily tools are absent: verify the group has a `tavily` MCP entry, then\n  restart it.\n- Crawl, Map, or Research appears: restore all three `--ignore-tool` pairs.\n- `429` or `monthly_cap_reached_bonus_eligible`: the keyless allowance is\n  exhausted; see [Keyless limit](#keyless-limit) for the OneCLI upgrade path.\n- The agent reports exhaustion but never offers the upgrade: check that\n  `groups/<group-folder>/instructions.prepend.md` contains the\n  `tavily-upgrade` block (Phase 5) and restart the group. A session that\n  already discussed the limit keeps reasoning from that history; `/clear`\n  starts a clean one.\n\n## Removal\n\nSee [REMOVE.md](REMOVE.md) for the idempotent removal procedure.\n\n## References\n\n- [Tavily Remote MCP](https://docs.tavily.com/documentation/mcp)\n- [`mcp-remote`](https://github.com/geelen/mcp-remote)","author":"@nanocoai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/add-tavily-tool","license":"MIT","category":"writing","lang":"en","tokens":1721,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"REMOVE.md","size":1332,"sha256":"c60ac82d2d0e2ade796390d43d0f46261874524dcf9c43f77ee34bb5ab8144cb"},{"path":"tavily-manifest.test.ts","size":1299,"sha256":"cee0792d96b2db1478f7427d97fa74c257671acb896d82291ab0858157df162c"},{"path":"upgrade-instructions.md","size":1440,"sha256":"7ea1c29f66da335e8e2d623c448d4cacec005eda8c14e99750c84b59c2d7a989"}],"requires":{"mcp":["tavily"],"tools":[]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"app.tavily.com, docs.tavily.com, mcp.tavily.com","message":"bundled scripts reach 3 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["app.tavily.com","docs.tavily.com","mcp.tavily.com"]}}