Skip to main content
Glama
iKwesi

Tavily Web Search MCP Server

by iKwesi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

AI Makerspace: MCP Session Repo for Session 13

This project is a demonstration of the MCP (Model Context Protocol) server, which utilizes the Tavily API for web search capabilities. The server is designed to run in a standard input/output (stdio) transport mode.

Related MCP server: Tavily Web Search MCP Server

Project Overview

The MCP server is set up to handle web search queries using the Tavily API. It is built with the following key components:

  • TavilyClient: A client for interacting with the Tavily API to perform web searches.

Prerequisites

  • Python 3.13 or higher

  • A valid Tavily API key

⚠️NOTE FOR WINDOWS:⚠️

You'll need to install this on the Windows side of your OS.

This will require getting two CLI tool for Powershell, which you can do as follows:

  • winget install astral-sh.uv

  • winget install --id Git.Git -e --source winget

After you have those CLI tools, please open Cursor into Windows.

Then, you can clone the repository using the following command in your Cursor terminal:

git clone https://AI-Maker-Space/AIE8-MCP-Session.git

After that, you can follow from Step 2. below!

Installation

  1. Clone the repository:

    git clone <repository-url>
cd <repository-directory>

  2. Configure environment variables: Copy the .env.sample to .env and add your Tavily API key:

    TAVILY_API_KEY=your_api_key_here

  3. 🏗️ Add a new tool to your MCP Server 🏗️

Create a new tool in the server.py file, that's it!

Running the MCP Server

To start the MCP server, you will need to add the following to your MCP Profile in Cursor:

NOTE: To get to your MCP config. you can use the Command Pallete (CMD/CTRL+SHIFT+P) and select "View: Open MCP Settings" and replace the contents with the JSON blob below.

{
    "mcpServers":  {
        "mcp-server": {
            "command" : "uv",
            "args" : ["--directory", "/PATH/TO/REPOSITORY", "run", "server.py"]
        }
    }
}

The server will start and listen for commands via standard input/output.

Usage

The server provides a web_search tool that can be used to search the web for information about a given query. This is achieved by calling the web_search function with the desired query string.

Activities:

There are a few activities for this assignment!

🏗️ Activity #1:

Choose an API that you enjoy using - and build an MCP server for it!

🏗️ Activity #2:

Build a simple LangGraph application that interacts with your MCP Server.

You can find details here!

Available Tools

3 tools
ask_specialized_claudeA

Call a specialized Claude model for targeted reasoning tasks.

This is "meta-AI" - Claude in Cursor calling another Claude instance with specialized system prompts for specific tasks. Each task_type activates a different Claude persona optimized for that use case.

Args: prompt: User input for Claude to process task_type: Specialization mode, one of: - code_review: Security and quality code analysis - summarize: Concise text summarization - explain: Educational explanations (ELI5 style) - creative: Creative writing and ideation - general: General-purpose assistance max_tokens: Response length cap (default 1024, max 4096)

Returns: A formatted string response from the specialized Claude instance

Examples: >>> ask_specialized_claude("Explain quantum computing", "explain") >>> ask_specialized_claude("Review this code: def foo()...", "code_review") >>> ask_specialized_claude("Summarize this article...", "summarize")

Raises: ValueError: If task_type is not recognized Exception: If API call fails (network, auth, rate limit, etc.)

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
task_typeNogeneral
max_tokensNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and does well. It discloses this is 'meta-AI' (Claude calling Claude), mentions different personas per task_type, includes error handling details (raises ValueError for unrecognized task_type, Exception for API failures), and describes the return format. It doesn't mention rate limits or auth specifics, but covers key behavioral aspects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and appropriately sized. It starts with a clear purpose statement, explains the meta-AI concept, details parameters with examples, and covers returns and errors. Every sentence adds value with zero waste, and it's front-loaded with the most important information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (AI calling AI with multiple specializations), no annotations, and 0% schema coverage, the description is remarkably complete. It explains the tool's unique nature, all parameters thoroughly, provides examples, documents return values and errors. With an output schema present, it doesn't need to explain return format details, making this description comprehensive for its context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all 3 parameters. It defines 'prompt' as 'User input for Claude to process', lists all valid 'task_type' values with their purposes, and explains 'max_tokens' as 'Response length cap' with default and maximum values. This adds significant meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Call a specialized Claude model for targeted reasoning tasks.' It specifies the verb ('Call'), resource ('specialized Claude model'), and distinguishes it from sibling tools (roll_dice, web_search) by focusing on AI reasoning rather than random generation or web search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: for 'targeted reasoning tasks' with different 'task_type' specializations. It doesn't explicitly state when NOT to use it or name alternatives among siblings, but the specialization context is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

roll_diceA

Roll dice with D&D-style notation (e.g., 2d20k1).

Args: notation: Dice notation (e.g., "2d20k1" = roll 2d20, keep highest 1) num_rolls: Number of times to roll (default 1)

Returns: Formatted dice roll results

ParametersJSON Schema
NameRequiredDescriptionDefault
notationYes
num_rollsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It discloses the core behavior (rolling dice with specific notation) and mentions the return format ('Formatted dice roll results'), but lacks details about error handling, rate limits, or specific formatting of outputs. The description doesn't contradict any annotations since none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a clear purpose statement, parameter explanations in a labeled 'Args' section, and return information. Every sentence earns its place by providing essential information without redundancy. The information is front-loaded with the core functionality stated first.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (2 parameters, no annotations, but has output schema), the description is mostly complete. It explains parameters well and mentions return formatting. The output schema existence means it doesn't need to detail return values, but could benefit from more behavioral context about error cases or limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate fully. It provides clear semantic explanations for both parameters: 'notation' is explained with examples and meaning ('2d20k1 = roll 2d20, keep highest 1'), and 'num_rolls' is explained with its default value and purpose. This adds significant value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Roll dice') with precise resource specification ('with D&D-style notation') and provides a concrete example ('e.g., 2d20k1'). It distinguishes itself from sibling tools like 'ask_specialized_claude' and 'web_search' by focusing on dice rolling functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through the example notation and default parameter, but doesn't explicitly state when to use this tool versus alternatives. No guidance is provided on when not to use it or what alternatives might exist for similar tasks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv1.0.0
    • Addedask_specialized_claude
    • Changedroll_dice2 fields changed
      • addedInput schema / title
        Added value: +"roll_diceArguments"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "title": "Result",
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "roll_diceOutput",
+  "type": "object"
+}
    • Changedweb_search2 fields changed
      • addedInput schema / title
        Added value: +"web_searchArguments"
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "title": "Result",
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "web_searchOutput",
+  "type": "object"
+}
    • RemovedYOUR_TOOL_NAME
  2. 3 tool updates
    • First observedroll_dice
    • First observedweb_search
    • First observedYOUR_TOOL_NAME
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0

Scored across 3 tools

Disambiguation5/5

The three tools have completely distinct purposes with no overlap: ask_specialized_claude handles AI reasoning tasks, roll_dice performs dice rolling, and web_search conducts web searches. Each tool targets a different domain (AI assistance, gaming utilities, and information retrieval), making them easily distinguishable.

Naming Consistency2/5

The naming conventions are inconsistent across tools: ask_specialized_claude uses a verb_object pattern, roll_dice uses a verb_noun pattern, and web_search uses a noun_verb pattern. There's no unified naming scheme, and the patterns vary significantly between tools.

Tool Count2/5

With only 3 tools, the set feels thin and poorly scoped for a 'Tavily Web Search MCP Server' as named. The inclusion of dice rolling and AI calling alongside web search suggests a mismatched collection rather than a coherent server focused on web search functionality.

Completeness2/5

For a web search server, having just one search tool (web_search) is insufficient. Missing are tools for advanced search parameters, result filtering, search history, or domain-specific searches. The other two tools (AI calling and dice rolling) don't contribute to web search completeness, creating a fragmented surface.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • metasearch-mcp

    YeonwooSung
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for using various search tools like Tavily API. Planning to support various search tools (i.e. wiki search, searxng, etc)
    3
    MIT

  • Tavily Web Search MCP Server

    julie-berlin
    F
    license
    C
    quality
    D
    maintenance
    Enables web search capabilities through the Tavily API, allowing users to search the internet for information using natural language queries. Demonstrates MCP server implementation with external API integration.
    3
    -

  • AI Makerspace MCP Demo Server

    lalrow
    F
    license
    A
    quality
    D
    maintenance
    Enables web search capabilities through the Tavily API and serves as a demonstration platform for building custom MCP tools. Designed for educational purposes to showcase MCP server development and LangGraph integration.
    6
    -