Skip to main content
Connector ID: mcp-tavily · Type: mcp_server · Catalog entry: src/gaia/connectors/catalog/mcp_servers.py

​
What you’ll need

Tavily is a web-search API built for AI agents. The connector is an MCP server — GAIA spawns the tavily-mcp process on demand via npx and routes tool calls (tavily-search, tavily-extract) through it, so the tools become available to all GAIA agents. It needs a single secret: a Tavily API key. You’ll create one, paste it into GAIA once, and you’re done. The key lives encrypted in your OS keyring; the MCP server reads it via a $keyring reference at launch.

​
Step 1 — Get an API key

  1. Sign in at app.tavily.com.
  2. Copy your API key from the dashboard. It starts with tvly- followed by a string of characters (e.g. tvly-AbCd…). If your key doesn’t start with tvly-, you’re looking at the wrong value.
The free tier includes a monthly credit allowance; a basic search costs 1 credit and an advanced search costs 2.

​
Step 2 — Configure GAIA

From the CLI:
From the Agent UI:
  1. Launch the Agent UI: gaia chat --ui.
  2. Settings (gear) → Connections → click the Tavily tile.
  3. Paste the key into the Tavily API Key field and click Save.
Either path stores the key in your OS keyring (a single slot, distinct from other connectors) and writes a $keyring reference into ~/.gaia/mcp_servers.json — the key never lives in plaintext on disk.

​
Step 3 — Use it

Once configured, grant and activate the tavily-search / tavily-extract MCP tools for each agent that should use them. For MCP servers a grant covers credential access, but the agent won’t see the tools until you also activate them (activation defaults to OFF):
(In the UI: the tile’s Per-agent toggle flips both at once.) See the connections security model for why visibility and credential access are gated separately. GAIA also ships a Python wrapper (gaia.web.tavily) used by web-research workflows, with response caching, a credit budget, and a CLI:
If the connector isn’t configured, gaia knowledge search and the wrapper fall back to a keyless DuckDuckGo search — so search works out of the box, and Tavily simply upgrades its quality and adds extract/crawl.

​
Common issues

​
Unauthorized / 401 from the MCP server

The key in your keyring is wrong or revoked. Click Disconnect on the tile (or gaia connectors disconnect mcp-tavily) and re-add a fresh key.

​
npx: command not found

tavily-mcp is launched via npx. Install Node 18+ and ensure npx is on your PATH:

​
Budget exceeded

gaia knowledge warns (if nearing the budget) then blocks once a session passes its --budget credit cap. Raise the cap, or pass --no-block to warn and proceed instead of blocking.

​
Revoking access

  • From GAIA: Settings → Connections → Tavily → Disconnect (or gaia connectors disconnect mcp-tavily). The key is removed from the keyring and the entry is dropped from mcp_servers.json.
  • From Tavily: rotate or delete the key in your Tavily dashboard.

​
See also