# Agno Search Agent MCP Project

## Overview

This project is a Model Context Protocol (MCP) server called **Agno Search Agent** built using the FastMCP Python framework and Agno agentic AI framework. It demonstrates how to integrate AI agents with web search capabilities into Claude Desktop via MCP. The agent uses DuckDuckGo for web searches and OpenAI GPT-4 for intelligent analysis.

***

## Code Explanation

### main.py

- Implements the MCP server using the FastMCP framework.
- Integrates an Agno agent with DuckDuckGo web search tools.
- Registers a `search` tool that processes queries through an AI agent.
- Uses OpenAI GPT-4 for analyzing and summarizing search results.
- Suppresses Python warnings to maintain clean MCP protocol communication.
- Runs as an MCP server listening for client connections.

### test_client.py

- A test client script to connect and interact with the MCP server locally.
- Demonstrates usage of the `search` tool and verifies functionality.
- Validates server connection and tool availability.

### client.py

- Provides a Streamlit-based client for interactive querying via a web UI.
- Uses asyncio to communicate with the MCP server and submit search queries.
- Allows end users to enter search prompts and view results in the browser.
- Intended for local demonstration and testing, separate from Claude Desktop integration.

***

## Running and Scope of `client.py`

`client.py` implements a minimal Streamlit application that provides a web interface for querying the MCP server directly from your browser. It connects to the running MCP server, submits queries to the `search` tool, and displays the results interactively.

**To launch the client interface:**
1. Run the MCP server using:
   uv run main.py

2. In a separate terminal window, start the Streamlit client:
   streamlit run client.py

3. Open `http://localhost:8501` in your browser. Enter any search query and click the "Search" button to view the summarized results generated by the Agno agent.

**Scope:**
- The Streamlit client demonstrates direct querying of the MCP server and real-time AI search analysis.
- It is *not* required for Claude Desktop integration. For Claude Desktop, MCP server communication happens natively between the desktop app and your running server.
- `client.py` is useful for standalone or development testing, letting you verify agent and tool functionality from a modern browser UI without the need for third-party chat clients.

***

## Prerequisites

- Python 3.10 or higher
- OpenAI API key (for GPT-4 access)
- UV package manager (recommended)
- Claude Desktop application (for integration, optional)
- Streamlit package (only required if using client.py UI)

***

## Installation and Setup Instructions

### Step 1: Install UV (Universal Version Manager)

UV is a modern Python package manager used to manage project environments and dependencies.

macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify installation:
uv --version

***

### Step 2: Set Up the Project Locally

Create and navigate to the project directory:
mkdir agentic_mcp
cd agentic_mcp

Initialize the UV project environment:
uv init

Install dependencies:
uv pip install fastmcp agno openai duckduckgo-search python-dotenv streamlit

Place your main.py, test_client.py, and client.py files inside this directory.

***

### Step 3: Configure OpenAI API Key

Create a .env file in the project directory:
echo "OPENAI_API_KEY=sk-your-actual-key-here" > .env

Replace sk-your-actual-key-here with your OpenAI API key.

***

### Step 4: Running the MCP Server Locally

Test the server locally before integrating with Claude Desktop:

Run the server:
uv run main.py

In another terminal, test with the client:
uv run test_client.py

Expected output:
=== Testing MCP Server Locally ===

✓ Server connected

Available tools: ['search']

Testing search tool...
Result:
[Search results analyzed by AI agent]

***

### Step 5: Using the Streamlit Client (Optional UI)

Start the MCP server as above. Then, in a new terminal run:
streamlit run client.py

- Access the interface at http://localhost:8501
- Enter a prompt and submit
- Results will be processed by the Agno agent through the MCP server and shown in-browser

***

### Step 6: Integrating the MCP Server with Claude Desktop

To integrate your MCP server with Claude Desktop:

- Ensure MCP server runs and is accessible from Claude Desktop.
- Configure Claude Desktop to connect as an MCP client to this server.
- Use MCP client interface in Claude Desktop to call the search tool.
- Process returned results within Claude Desktop for seamless integration.

On Windows:
fastmcp install claude-desktop main.py --with agno --with openai --with ddgs --with duckduckgo-search --with python-dotenv

Alternatively:
cd agentic_mcp
fastmcp install claude-desktop main.py \
  --with agno \
  --with openai \
  --with ddgs \
  --with duckduckgo-search \
  --with python-dotenv \
  --env OPENAI_API_KEY=sk-your-actual-key-here

Restart Claude Desktop completely.

***

## Debugging

### View Server Logs

Windows:
Get-Content "$env:APPDATA\Claude\logs\mcp-server-Agno-Search-Agent.log" -Wait -Tail 20

macOS/Linux:
tail -f ~/Library/Application\ Support/Claude/logs/mcp-server-Agno-Search-Agent.log

### Common Issues

1. Server disconnects immediately
    - Check OpenAI API key is correct
    - Verify all dependencies installed: uv pip list

2. Module not found errors
    - Install missing packages: uv pip install <package-name>
    - Check paths in config are absolute

3. Protocol errors
    - Ensure main.py includes warning suppression code
    - Check no print statements outputting to stdout

***

## Project Structure

agentic_mcp/
├── main.py              # MCP server with Agno agent
├── test_client.py       # Local testing client
├── client.py            # Streamlit web client (optional)
├── .env                 # OpenAI API key (create this)
├── README.md            # This file
└── .python-version      # Python version (auto-generated by uv)

***

## Summary of Commands

Install UV (Windows example)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Setup project folder and initialize
mkdir agentic_mcp && cd agentic_mcp
uv init

Install dependencies
uv pip install fastmcp agno openai duckduckgo-search python-dotenv streamlit

Create .env file
echo "OPENAI_API_KEY=sk-your-key" > .env

Test locally
uv run test_client.py

Optional: start Streamlit UI
streamlit run client.py

Install for Claude Desktop (automatic)
fastmcp install claude-desktop main.py \
  --with agno --with openai --with ddgs --with duckduckgo-search \
  --with python-dotenv --env OPENAI_API_KEY=sk-your-key

***

## How It Works

1. Claude Desktop sends a search request to the MCP server
2. MCP Server receives the query through the search tool
3. Agno Agent processes the query using DuckDuckGo search tool
4. OpenAI GPT-4 analyzes search results and generates summary
5. Response is sent back to Claude Desktop for display

***

## Example Usage

User query in Claude Desktop:
Search for the latest India vs Australia cricket match results

Agno Agent workflow:
1. Receives search query
2. Executes DuckDuckGo search
3. Analyzes multiple search results
4. Generates comprehensive summary with key details
5. Returns formatted response to Claude

***

Built with FastMCP & Agno | Agentic AI with MCP