Skip to main content
Glama
rach16

MCP Server for Session 13

by rach16
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: Create a .env file and add your API keys:

    TAVILY_API_KEY=your_tavily_api_key_here
NEWS_API_KEY=your_news_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 several tools for different functionalities:

Available Tools:

  1. web_search(query: str) - Search the web for information about a given query using Tavily API

  2. roll_dice(notation: str, num_rolls: int) - Roll dice with custom notation (e.g., "2d6", "1d20")

  3. get_marketing_news(company: str, category: str, num_articles: int) - Get latest marketing and business news from companies like ZoomInfo, 6sense, HubSpot, etc.

  4. get_company_news(company: str, num_articles: int) - Get specific news about a particular company

Example Usage:

  • get_marketing_news() - Get general marketing tech news

  • get_marketing_news(company="ZoomInfo") - Get ZoomInfo-specific news

  • get_company_news(company="6sense") - Get 6sense company news

  • roll_dice("2d6", 3) - Roll 2 six-sided dice 3 times

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.

Files for Activity #2:

  • langgraph_app.py - LangGraph application with MCP integration

To test Activity #2:

uv run langgraph_app.py

Available Tools

4 tools
get_company_newsA

Get specific news about a particular company (e.g., ZoomInfo, 6sense, etc.)

Args: company: Company name to search for num_articles: Number of articles to return (default: 3)

ParametersJSON Schema
NameRequiredDescriptionDefault
companyYes
num_articlesNo

TDQS

A3.6/5.0
Behavior3/5

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

The description indicates a read operation (get news) with no destructive hints. However, without annotations, it does not disclose details like rate limits, pagination, or source of news, leaving some behavioral ambiguity.

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

Conciseness4/5

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

The description is short and mostly clear, though the Args block duplicates schema information. The core purpose sentence is well-placed. Minor redundancy but no unnecessary verbosity.

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

Completeness3/5

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

For a simple tool with 2 parameters and no output schema, the description covers the basic function. It is missing output format details (e.g., headlines vs. full articles) and potential constraints, but is minimally adequate.

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

Parameters4/5

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

With 0% schema coverage, the description adds semantic value by explaining each parameter: 'Company name to search for' and 'Number of articles to return (default: 3)'. This compensates for the bare schema (which only has titles).

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 gets company-specific news, with examples (e.g., ZoomInfo, 6sense). It distinguishes from siblings like 'get_marketing_news' (broader marketing news) and 'web_search' (general web results).

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives. The description implies it is for company-specific news, but lacks when-not-to-use criteria or references to sibling tools.

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

get_marketing_newsB

Get the latest marketing and business news from companies like ZoomInfo, 6sense, and other marketing tech companies.

Args: company: Specific company to search for (e.g., 'ZoomInfo', '6sense', 'HubSpot', 'Salesforce') category: News category (default: 'business', options: 'business', 'technology', 'general') num_articles: Number of articles to return (default: 5, max: 100)

ParametersJSON Schema
NameRequiredDescriptionDefault
companyNo
categoryNobusiness
num_articlesNo

TDQS

B3.1/5.0
Behavior2/5

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

No annotations provided, so description carries full burden. It does not disclose if the tool is read-only, has side effects, requires authentication, or any rate limits. Only describes basic functionality.

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

Conciseness4/5

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

Concise paragraph followed by a structured Args list. Front-loaded with purpose. Could trim minor redundancy but overall efficient.

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

Completeness3/5

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

Adequately covers parameters and purpose given no annotations or output schema. Lacks guidance on use cases, return format, or limitations, but is sufficient for basic usage.

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

Parameters4/5

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

Schema description coverage is 0%, but the description's Args section explains each parameter (company, category, num_articles) with examples and defaults, adding meaning beyond the schema's type and default values.

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

Purpose4/5

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

The description clearly states the tool retrieves the latest marketing and business news from specific companies like ZoomInfo and 6sense. The verb 'Get' and resource 'marketing and business news' are specific, but lacks explicit differentiation from sibling tool 'get_company_news'.

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

Usage Guidelines2/5

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

Provides examples of companies and categories but no guidance on when to use this tool versus alternatives like 'get_company_news'. No when-not-to-use or prerequisites mentioned.

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

roll_diceC

Roll the dice with the given notation

ParametersJSON Schema
NameRequiredDescriptionDefault
notationYes
num_rollsNo

TDQS

C2.3/5.0
Behavior1/5

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

No annotations are present, so the description must disclose behavioral traits. It only says 'Roll the dice,' which is a direct restatement of the tool name and adds no depth about random generation, validation, error handling, or return format. This is effectively a tautology with no added transparency.

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

Conciseness3/5

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

The description is a single concise sentence with no waste, which is positive. However, it is under-specified: it front-loads little useful information and does not structure any context for the parameters. It cannot be considered 'appropriately sized' because it omits essential detail.

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

Completeness1/5

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

For a tool with two parameters, no output schema, and no annotations, the description is severely inadequate. It does not explain dice notation, the meaning of num_rolls, or any behaviors/limitations. Even the sibling context (web_search) offers no help in situating this tool, making the description insufficient for reliable tool invocation.

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

Parameters2/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. 'Given notation' loosely aligns with the 'notation' parameter but fails to define its format or semantics. The 'num_rolls' parameter is entirely absent from the description, leaving its purpose unexplained. Overall, minimal added meaning beyond the schema titles.

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

Purpose4/5

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

The description states a clear verb ('Roll') and resource ('dice'), indicating the tool's primary action. However, it does not specify what 'notation' means (e.g., standard dice notation like '2d6'), which leaves some ambiguity. It is distinct from the sibling web_search, but not explicitly differentiated.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool vs alternatives. The sibling list includes web_search, but the description gives no context for when dice rolling is appropriate or any exclusions. Users are left to infer usage from the name alone.

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 updatesv0.1.0
    • First observedget_company_news
    • First observedget_marketing_news
    • First observedroll_dice
    • First observedweb_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.4/5.0

Scored across 4 tools

Disambiguation2/5

get_company_news and get_marketing_news have significant overlap, both retrieving news about marketing tech companies, making it unclear which to use. The other tools (roll_dice, web_search) are unrelated, further complicating disambiguation.

Naming Consistency2/5

Two tools follow a 'get_X_news' pattern, but roll_dice and web_search break that pattern, using different verb styles. The naming is inconsistent across the set.

Tool Count2/5

With only 4 tools spanning news, dice rolling, and web search, the count feels arbitrary and too small for a coherent domain. The server appears to bundle unrelated utilities.

Completeness1/5

The coverage is severely incomplete for any clear purpose. If focused on marketing news, dice rolling and web search are extraneous; if general, many common operations are missing. The set lacks a coherent domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Tavily Web Search MCP Server

    nilay320
    F
    license
    B
    quality
    D
    maintenance
    Enables web search capabilities through the Tavily API. Allows users to search the web for information using natural language queries via the MCP protocol.
    4
    1
    -

  • Tavily Web Search MCP Server

    vinitv
    F
    license
    C
    quality
    D
    maintenance
    Enables web search capabilities through the Tavily API. Allows users to search the web for information using natural language queries through the MCP protocol.
    3
    -

  • AI Makerspace MCP Server

    Swathi3255
    F
    license
    C
    quality
    D
    maintenance
    An MCP server providing tools for web searching via the Tavily API, dice rolling using standard notation, and cryptocurrency market data through the CoinGecko API. It is designed to integrate these capabilities into AI workflows using a standard input/output transport mode.
    3
    -