web-research-hub-mcp-server

FastAPI · FastMCP · Streamable HTTP · Exa AI · Python

A standalone MCP server that exposes the Web Research Hub's core research capabilities as standardized tools over Streamable HTTP — callable by Claude Desktop, Claude.ai, or any MCP-compatible agent or client.

Built as the infrastructure layer for web-research-hub, this server separates tool execution from agent reasoning: the LLM stays in the research app, the tools live here.

---

🔗 Live Endpoint

https://web-production-a8829.up.railway.app/mcp

Health check:

https://web-production-a8829.up.railway.app/health

---

Architecture

Client (Claude Desktop / Claude.ai / custom agent)
        │  POST /mcp  (MCP Streamable HTTP)
        ▼
  FastAPI + FastMCP
        │
  ┌─────┴────────────────────────────────────────┐
  │  web_search  fetch_url  calculate  export_report  │
  └─────┬──────────────────────────────────────────┘
        │
   Exa AI API    httpx + BS4    ast (stdlib)    fpdf2 / python-docx

• Transport: Streamable HTTP — clients POST to /mcp
• Health check: GET /health — public, no auth required
• CORS: configurable via CORS_ORIGIN_REGEX env var

---

How It Fits the Portfolio

This server is part of a three-tier architecture:

Web Research Hub (frontend + FastAPI backend)
  → calls this MCP server as a tool provider
  → agents use web_search and fetch_url during research
  → reports exported via export_report

This MCP Server
  → exposes 4 tools over Streamable HTTP
  → no LLM calls inside — pure tool execution
  → callable by any MCP-compatible client independently

Pinecone Agentic Search MCP Server
  → separate MCP server in this portfolio
  → handles academic/vector search over ArXiv corpus
  → uses SSE transport (contrast: this server uses
    Streamable HTTP — the newer MCP spec standard)

The two MCP servers in this portfolio demonstrate both transport patterns (SSE and Streamable HTTP) and two different tool scopes (single-purpose vector search vs. broader research toolkit).

---

What Makes This Different from the Pinecone MCP Server

	Pinecone MCP Server	This Server
Transport	SSE	Streamable HTTP
Tools	1 (agentic-search)	4 (web_search, fetch_url, calculate, export_report)
Data source	Pinecone vector store (ArXiv corpus)	Live web (Exa AI) + stdlib
LLM calls	Yes (OpenRouter)	None — pure tool execution
Purpose	Academic/research paper search	Web research tool layer

---

Tool Reference

web_search

Searches the live web via Exa AI and returns structured results with title, URL, summary, and publication date. Use when the research query requires current, real-world web sources. Returns an empty results array on failure, never throws.

Parameter	Type	Default	Notes
query	string	required	Search query
num_results	int	4	Max results to return
start_date	string	null	ISO 8601 date filter (e.g. 2024-01-01)
end_date	string	null	ISO 8601 date filter

Response:

{
  "results": [{ "title": "", "url": "", "summary": "", "published_date": "" }],
  "query": "...",
  "total_results": 4
}

Returns results: [] on failure, never throws.

---

fetch_url

Fetches a URL and returns clean extracted text, stripping HTML and truncating to the specified character limit. Use to go deeper on a specific source found during web search. Returns success: false on failure, never throws.

Parameter	Type	Default	Notes
url	string	required	Full URL to fetch
max_length	int	5000	Character limit on returned content

Response:

{ "url": "", "content": "", "title": "", "success": true }

---

calculate

Evaluates a safe arithmetic expression using Python's AST parser — no raw eval(). Use for numeric reasoning within research tasks (e.g. percentage changes, cost calculations, financial figures). Returns result: null with an error field on failure, never throws.

Parameter	Type	Default	Notes
expression	string	required	e.g. "(3 + 4) * 2"
description	string	null	Optional label for context

Supported operators: + - * / ** % //

Response:

{ "expression": "(3 + 4) * 2", "result": 14, "description": null }

---

export_report

Exports a markdown string to PDF, DOCX, or MD and returns the file as a base64-encoded string. Citation links [text](url) are rendered as text (domain.com) in PDF and DOCX output so sources remain identifiable outside the browser. Returns success: false on failure, never throws.

Parameter	Type	Default	Notes
content	string	required	Markdown source
format	string	required	"pdf", "docx", or "md"
title	string	null	Prepended as H1; used in filename

Response:

{
  "format": "pdf",
  "filename": "report.pdf",
  "content_base64": "...",
  "success": true
}

---

Design Constraints

No LLM calls inside this server. Every tool is a pure function: input → deterministic output. The LLM reasoning (planning, orchestration, synthesis) stays in the Web Research Hub's FastAPI backend agents. This is the correct MCP pattern — tools are execution units, not reasoning units.

Every tool is non-throwing. All external calls are wrapped in try/except. A tool that throws breaks the entire MCP session. Every tool returns a valid response object even on failure.

Tool descriptions are written as policies, not labels. Each tool description specifies what it does, when to use it, and what it returns on failure — not just a one-line label. This matches the prompt engineering standard applied across every agent in this portfolio.

---

Authentication

Every request to POST /mcp must include an X-API-Key header:

X-API-Key: your-secret-key-here

The key is compared against the MCP_API_KEY environment variable on the server. Missing or invalid keys return HTTP 401. GET /health requires no authentication.

---

Rate Limits

POST /mcp is limited to 10 requests per IP address per hour. Exceeding the limit returns HTTP 429. GET /health is not rate-limited.

Note: one search generates 4-5 /mcp calls internally (MCP handshake + one tool call per subtask), so this limit allows approximately 2 complete Quick searches per hour.

This is a portfolio demonstration server. To remove these limits, clone the repo and deploy your own instance with your own API keys.

---

Environment Variables

Variable	Required	Description
EXA_API_KEY	✅	Exa AI API key — get one at exa.ai
MCP_API_KEY	✅	Secret key callers must pass as X-API-Key header
CORS_ORIGIN_REGEX	optional	Regex for allowed origins. Default: https://.*\.vercel\.app

---

Local Development

# 1. Clone and enter the repo
git clone https://github.com/Paul-Orlando/web-research-hub-mcp-server.git
cd web-research-hub-mcp-server

# 2. Create a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
# Edit .env and add your EXA_API_KEY and MCP_API_KEY

# 5. Run the server
uvicorn main:app --reload

Verify it's running:

curl http://localhost:8000/health
# {"status":"ok","tools":["web_search","fetch_url","calculate","export_report"]}

---

Deployment

Railway (recommended)

Railway detects the Procfile automatically.

1. Push this repo to GitHub
2. New project → Deploy from GitHub repo
3. Root Directory: / (not a monorepo)
4. Set EXA_API_KEY and MCP_API_KEY in the Variables tab
5. Deploy — starts with:

uvicorn main:app --host 0.0.0.0 --port $PORT

6. Settings → Networking → Generate Domain → set Target Port to the port shown in deploy logs (typically 8080)
7. Test: GET https://your-url.up.railway.app/health

---

Connecting to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "web-research-hub": {
      "url": "https://web-production-a8829.up.railway.app/mcp",
      "headers": {
        "X-API-Key": "your-key-here"
      }
    }
  }
}

For local development use http://localhost:8000/mcp and set MCP_API_KEY in your local .env.

---

Usage Note

This is a portfolio demonstration server with rate limiting and API key authentication. For production use, clone the repo and deploy your own instance with your own API keys — the Procfile and Railway deployment instructions above are included for exactly this purpose.

---

Roadmap

• [ ] academic_search tool — calls the Pinecone Agentic Search MCP Server internally, making this server an MCP client of another MCP server in this portfolio (three-tier pattern)
• [ ] Source credibility scoring — weight academic/primary sources higher than secondary commentary
• [ ] Tool call logging for observability

---

Related Repos

Repo	Pattern	Stack
web-research-hub	Hierarchical 3-Agent Pipeline	Next.js · FastAPI · OpenRouter · Gemini 2.5 Flash · Exa AI
pinecone-mcp-server	Custom MCP Server · Agentic RAG	Node.js · TypeScript · Pinecone · SSE
n8n-mcp-server-agentic-rag	Agentic RAG + MCP Client	Node.js · Express · Pinecone · Gemini Flash 2.5

---

Author

Paul Orlando Creative Technologist | AI Agent Developer | Data Analytics 🌐 paulforlando.com  |  💼 LinkedIn  |  🐙 GitHub

---

License

MIT License