MCP Bootstrap

A minimal, runnable project for learning the Model Context Protocol (MCP) — the open standard that lets AI apps discover and call tools from external servers.

You get both sides of the wire:

File	Role	What it does
research_server.py	MCP Server	Exposes search_papers and extract_info tools
mcp_chatbot.py	MCP Client / Host	Starts the server, lists tools, lets Gemini call them
main.py	Helper	Prints a quick map of the project

---

How MCP fits together

┌─────────────────┐         stdio (JSON-RPC)        ┌──────────────────┐
│  Host / Client  │ ◄──────────────────────────────► │   MCP Server     │
│  mcp_chatbot.py │   list_tools / call_tool         │ research_server  │
│  + Gemini LLM   │                                  │  • search_papers │
└─────────────────┘                                  │  • extract_info  │
                                                     └──────────────────┘

1. The host starts the server as a subprocess (stdio transport).
2. It calls list_tools — the server returns schemas for each @mcp.tool().
3. Those schemas are given to the LLM as function declarations.
4. When the model wants data, the host runs call_tool on the MCP session and feeds the result back.

Same server can also be plugged into Cursor or Claude Desktop — that’s the point of the protocol.

---

Prerequisites

• Python 3.11+
• uv (recommended) or pip + venv
• A free Gemini API key

Install uv (if you don’t have it)

# macOS / Linux
brew install uv

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

---

Setup

1. Clone the repo

git clone <your-repo-url>
cd mcp_project   # or whatever you named the folder

2. Configure your API key

cp .env.example .env

Open .env and set:

GEMINI_API_KEY=your_key_here

3. Install packages

Option A — uv (recommended)

uv sync

This creates a virtualenv (.venv) and installs everything from pyproject.toml:

Package	Why it’s needed
mcp	MCP client + FastMCP server SDK
google-genai	Gemini API for the chatbot host
arxiv	Search papers in search_papers
python-dotenv	Load .env for the API key

Option B — pip + venv

python -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows
# .venv\Scripts\activate

pip install -U pip
pip install mcp google-genai arxiv python-dotenv

---

Run the full demo (client + server)

With uv:

uv run mcp_chatbot.py

With pip / activated venv:

python mcp_chatbot.py

You’ll see lines like → MCP tool: search_papers(...) when the LLM decides to use a tool.

Try these questions

Copy-paste any of these after the chatbot starts:

Search papers (search_papers)

Find 3 papers about transformers
Search for 5 papers on reinforcement learning
Find recent papers about quantum computing
Search arXiv for graph neural networks, max 2 results
What papers exist on attention mechanisms in NLP?

Look up a paper (extract_info)

Tell me about paper 1706.03762
What is the summary of paper 1706.03762?
Who are the authors of paper 1706.03762?
Give me the title and PDF link for paper 1706.03762

Combine both tools

Search for papers on transformers, then summarize the first one
Find 3 physics papers and tell me what the first paper is about
Search for algorithms papers and list their titles

Tip: run a search first so papers are cached under papers/, then ask about a specific paper ID from the results.

Or just print the project map:

uv run main.py
# or: python main.py

---

Run the server alone

Useful when connecting from Cursor / Claude Desktop:

uv run research_server.py
# or: python research_server.py

This process speaks MCP over stdin/stdout. Don’t type into it manually — a host drives it.

Cursor / Claude Desktop config example

Add something like this to your MCP settings (adjust the path):

{
  "mcpServers": {
    "research": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp_project",
        "run",
        "research_server.py"
      ]
    }
  }
}

---

Tools exposed by the server

search_papers(topic, max_results=5)

Queries arXiv, caches metadata under papers/<topic>/papers_info.json, returns paper IDs.

extract_info(paper_id)

Looks up a cached paper by ID across all topic folders.

---

Project layout

.
├── research_server.py   # MCP server (tools)
├── mcp_chatbot.py       # MCP client + Gemini tool loop
├── main.py              # Quick orientation
├── papers/              # Local cache created by search_papers
├── .env.example         # Copy → .env (never commit secrets)
├── mcp_config.example.json  # Sample Cursor / Claude Desktop MCP config
├── pyproject.toml
├── LICENSE
└── README.md

---

Learning path

1. Read research_server.py — how FastMCP registers tools.
2. Read mcp_chatbot.py — connect → list_tools → LLM → call_tool.
3. Run the chatbot and watch tool calls print in the terminal.
4. Point Cursor at the same server and ask the same questions in the IDE.

---

Notes

• Generated paper caches live in papers/ (gitignored except .gitkeep).
• Keep secrets in .env only — .env is gitignored.
• Default model is gemini-2.5-flash; override with GEMINI_MODEL in .env.

---

License

MIT — use this as a learning starter for your own MCP servers.