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

Related MCP server: Exa Websets MCP Server

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

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.

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.

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.

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.

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

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

Author

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

License

MIT License