Overview

The Tavily MCP Server implements a Model Context Protocol (MCP) endpoint that lets teams discover, search, and extract structured insights from AI agents and their interactions. It indexes the pieces of agent behavior — prompts, tools, chains, and outputs — and exposes them through a simple HTTP API so you can query what an agent did, why it made a decision, or reuse parts of an agent for new workflows.

This server is useful when you want fast, programmatic access to an inventory of agent artifacts for debugging, auditing, knowledge extraction, or building search-driven interfaces. Instead of digging through logs or siloed prompt files, the MCP Server centralizes agent context and provides search/extraction primitives you can integrate into developer tools, dashboards, or retrieval-augmented generation pipelines.

Features

Index and expose agent artifacts: prompts, chains, tools, and execution traces
Full-text and vector search across agent context
Extraction APIs to pull structured prompts, examples, and decisions
RESTful HTTP endpoints suitable for dashboards, CLIs, and server-side integrations
Configurable storage backend and API keys for access control
OpenAPI-compatible schema for easy SDK generation and automation

Installation / Configuration

Clone the repository and run locally. The project is distributed with typical Node.js tooling; adjust commands to your package manager if needed.

Clone and install dependencies

git clone https://github.com/tavily-ai/tavily-mcp.git
cd tavily-mcp
npm install

Create a .env file with the required configuration (example variables shown):

# .env
PORT=8080
NODE_ENV=development
DATABASE_URL=postgresql://user:pass@localhost:5432/tavily
VECTOR_DB_URL=http://localhost:8001
API_KEY=your-server-api-key
LOG_LEVEL=info

Run in development

npm run dev
# or
NODE_ENV=development npm start

Run with Docker

# build
docker build -t tavily-mcp .

# run (example)
docker run -e PORT=8080 -e API_KEY=your-server-api-key -p 8080:8080 tavily-mcp

Note: The server can be configured to use different storage backends (SQL, vector DBs). Set the environment variables for your chosen backend and restart the server.

Available Resources

The MCP server exposes a small set of REST endpoints to interact with the indexed agent context. The exact routes and payloads may vary by version; below is a representative table and examples to get started.

Method	Path	Description
GET	/health	Health check and status
GET	/api/agents	List indexed agents and metadata
GET	/api/agents/:id	Retrieve agent manifest and config
POST	/api/search	Search agent context (text or vector queries)
POST	/api/extract	Extract structured pieces (prompts, examples, tool usages)
GET	/openapi.json	OpenAPI schema for automated tooling

Example: search request

curl -X POST "http://localhost:8080/api/search" \
  -H "Authorization: Bearer your-server-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query":"summarize customer support conversation","top_k":5}'

Example response (abridged)

{
  "results": [
    {
      "agent_id": "support-bot-v1",
      "score": 0.87,
      "snippet": "Prompt: Summarize the conversation and propose next action"
    }
  ]
}

Example: extraction request

curl -X POST "http://localhost:8080/api/extract" \
  -H "Authorization: Bearer your-server-api-key" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"support-bot-v1","extract":["prompts","examples"],"limit":10}'

Use Cases

Debugging agent behavior: Search for prompts, tool calls, or specific tokens across agent versions to understand why an agent produced a given output.
- Example: find all prompts that include “refund policy” to see how customer support agents handle refunds.
Prompt and example re-use: Extract canonical prompts and few-shot examples to reuse across different agents or to A/B test alternative phrasing.
- Example: extract top 5 prompts for “onboarding email” and plug them into a new agent.
Observability and auditing: Provide compliance teams with a searchable index of agent interactions and decision rationales for traceability.
- Example: produce an audit report listing tool calls and external API accesses for a timeframe.
Search-driven UIs: Build an internal portal that lets non-technical stakeholders search agent capabilities, preview prompt snippets, and deploy selected flows into staging.
- Example: a UI that queries /api/agents and /api/search to let product managers discover agent behaviors.
Augmented generation: Combine extracted prompts and examples with a retrieval-augmented generation pipeline to improve response relevance.
- Example: at runtime, call /api/search to fetch context-relevant prompts and include them as context to the LLM.

Getting Help and Contributing

Visit the GitHub repository for source, issues, and contribution guidelines: https://github.com/tavily-ai/tavily-mcp. The project typically includes an OpenAPI spec and docs in the repo to help generate client SDKs and integrate the server into CI/CD workflows.

Tavily MCP Server: AI Agent Search and Extraction