Skip to main content
Glama
mcp-tavily

mcp-tavily

by openplayx

mcp-tavily

English | 简体中文

License: MIT

Web search MCP server for OpenPlayX, backed by Tavily and running on Cloudflare Workers: https://mcp-tavily.openplayx.com/mcp.

The app ships it as a preset external capability (lib/services/external/external_presets.dart): on first launch it is added to AI → 外部能力 (External capabilities), and the model sees the tool as mcp_tavily_web_search. If the user deletes it, it is not added back.

Endpoints

Path

Description

POST /mcp

MCP Streamable HTTP (JSON responses only, stateless, no Mcp-Session-Id). Supports initialize, ping, tools/list, tools/call and notifications; protocol versions 2025-11-25 / 2025-06-18 / 2025-03-26

GET /mcp

405; no server-initiated stream

GET /health

{"ok":true,"search":<configured and enabled>}

Authentication: Authorization: Bearer <the app's anonymous install ID>, 16–64 characters of [A-Za-z0-9-]. It is not a secret; it only identifies an installation for quota counting.

Tool web_search

Arguments: query (1–300 characters), count (1–10, default 8), time_range (day / week / month / year). Returns: {"results":[{title,url,snippet?,date?}],"cached":bool}.

Business errors are tool results with isError: true and structuredContent {"error":{status,code,message,retryable,detail?}}, the same shape as the other mcp-* services:

code

Meaning

quota_exceeded (429)

Today's free searches are used up; detail.scope is device / ip / global. The app has no other search fallback, so the assistant tells the user

service_unavailable (503)

Search is switched off, the Tavily key is missing or invalid, or the Tavily account is out of credits

upstream_unavailable / upstream_changed (502)

Tavily failed

invalid_request (400)

Invalid arguments

Related MCP server: groundlink-mcp

Design

  • The Tavily key lives only here, as the Worker secret TAVILY_API_KEY: never in the repository, never in the app.

  • Quotas (per UTC day): DEVICE_DAILY_LIMIT per installation, IP_DAILY_LIMIT per IP and GLOBAL_DAILY_LIMIT overall. Counters live in a SQLite Durable Object (Quota), exact and atomic; upstream failures refund the quota. IPs are stored only as hashes.

  • Cache: identical queries (case-insensitive) with the same count and time_range are served from the edge cache for 6 hours, at no quota or cost.

  • Kill switch: set SEARCH_ENABLED to "false" and redeploy.

  • Install IDs can be changed at will, so the per-install quota is a soft limit. Cost is really bounded by the global limit plus the spending limit set in the Tavily dashboard.

  • When the tool definition changes, update the copy bundled in the app (ExternalPresets.tavily.toolDefs); the app's live test compares the two.

Using it from other MCP clients

The hosted instance is meant for the OpenPlayX app and has small quotas. To use it from other clients, deploy your own (below) and configure:

{
  "mcpServers": {
    "tavily": {
      "type": "http",
      "url": "https://<your-domain>/mcp",
      "headers": { "Authorization": "Bearer <any 16–64 character alphanumeric ID>" }
    }
  }
}

Develop and deploy

Requirements: Node.js 20+; for deployment a Cloudflare account (SQLite-backed Durable Objects work on the free plan) and a Tavily API key.

npm install
npm run smoke        # local end-to-end: wrangler dev + mock Tavily, small quotas
npx wrangler deploy  # deploy (binds the custom domain in wrangler.jsonc routes; DNS and certificate are automatic)
npx wrangler secret put TAVILY_API_KEY   # or add it in the dashboard under Settings → Variables and Secrets
npx wrangler tail    # live logs

For your own deployment, change routes in wrangler.jsonc to a domain on your Cloudflare account, or remove routes and set workers_dev to true to use a *.workers.dev address. Variables for local development go into .dev.vars (git-ignored).

To change quotas, edit vars in wrangler.jsonc and redeploy; the app needs no release.

Contributing

Issues and pull requests are welcome, see CONTRIBUTING.md. Report security problems privately as described in SECURITY.md.

Disclaimer

This project is not affiliated with Tavily. Results come from Tavily and third-party websites and are not guaranteed to be accurate. If you deploy your own instance, you must follow Tavily's terms of service and you pay for its use.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP hosts to perform cited web searches and receive source-bearing results with titles, URLs, snippets, and sources for evidence-grounded answers.
      1
      36 npm
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to run local web searches with automatic failover across multiple search providers and to extract public web pages as titles and Markdown content, using circuit breaking and key-redacted logging.
      -