Research Intelligence MCP

A production-structured Model Context Protocol (MCP) server for academic paper discovery, citation exploration, and research intelligence workflows.

Research Intelligence MCP provides a unified interface over multiple scientific knowledge sources while exposing standardized MCP tools that can be consumed by AI systems such as ChatGPT, Claude Desktop, Cursor, ResearchMind, and custom agents.

Connects as a standard MCP server into Claude Desktop, Cursor, or applications like ResearchMind

One query fans out across Semantic Scholar, arXiv, and returning a single unified result set.

Rich, structured paper metadata — abstracts, citations, and open-access links — surfaced directly in conversation.

Motivation

Modern AI systems increasingly require access to external research knowledge.

Academic information is fragmented across multiple providers:

• Semantic Scholar

• arXiv

• OpenAlex

• CrossRef

• PubMed

• IEEE

• Springer

• Nature

Every provider exposes different APIs, schemas, identifiers, and capabilities.

This project solves that problem by providing:

• Unified paper models

• Provider abstraction

• Search federation

• Citation graph exploration

• Open-access paper resolution

• MCP-compatible tooling

Features

Current Version

Academic Search

• Search scientific papers

• Search recent arXiv publications

• Retrieve paper metadata

• Discover related papers

• Retrieve citations and references

• Resolve available open-access PDFs

Architecture

• Official MCP Python SDK

• Async Python architecture

• Provider abstraction layer

• Canonical domain models

• Structured logging

• Retry policies

• Caching support

• Rate limiting support

• Production-quality project structure

Supported Providers

Related MCP server: Academic Paper MCP HTTP/SSE Server

Phase 1

• Semantic Scholar

• arXiv

Planned Providers

• CrossRef

• OpenAlex

• Papers With Code

• PubMed

• IEEE

• Springer Nature

Example Use Cases

Find recent papers

Find recent papers about Agentic RAG.

Discover related work

Find papers related to LangGraph multi-agent systems.

Citation exploration

What papers cite the original RAG paper?

Open-access resolution

Find the PDF for this research paper.

Research agent integration

ResearchMind
        ↓
Research Intelligence MCP
        ↓
Semantic Scholar
arXiv

Architecture

┌──────────────────────┐
│      MCP Tools       │
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│      Services        │
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│ Provider Abstraction │
└──────────┬───────────┘
           │
 ┌─────────┴─────────┐
 │                   │
▼                     ▼
Semantic Scholar     arXiv

Project Structure

research-intelligence-mcp/
├── src/
│   └── research_intelligence_mcp/
├── tests/
├── scripts/
│   └── generate_dev_token.py
├── deployment/
│   ├── ecs/
│   │   ├── task-definition.json
│   │   ├── service-connect-example.json
│   │   └── README.md
│   ├── observability/
│   │   ├── prometheus.yml
│   │   └── grafana/
│   └── scripts/
│       ├── smoke_test.py
│       └── wait_for_ready.py
├── Dockerfile
├── .dockerignore
├── docker-compose.yml
├── pyproject.toml
├── README.md
└── .env.example

Requirements

• Python 3.12+

• uv

• Git

Installation

Clone repository:

git clone <repository-url>
cd research-intelligence-mcp

Create virtual environment:

uv venv
source .venv/bin/activate

Install dependencies:

uv sync

Create environment file:

cp .env.example .env

Running

Run the MCP server:

uv run research-intelligence-mcp

or

python -m research_intelligence_mcp

Quality Checks

Format:

uv run ruff format .

Lint:

uv run ruff check .
uv run ruff check . --fix

Type checking:

uv run mypy src

Tests:

uv run pytest

Package build verification:

uv build

MCP Configuration Example

{
  "mcpServers": {
    "research-intelligence-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/research-intelligence-mcp",
        "run",
        "research-intelligence-mcp"
      ]
    }
  }
}

For full step-by-step instructions covering Claude Desktop, Cursor, MCP Inspector, and remote streamable-http clients (including bearer-JWT authentication), see docs/research_intelligence_mcp_client_setup.md.

Test using MCP Inspector

The official MCP Inspector is the recommended interactive tool for viewing registered MCP tools, their schemas, parameters, and execution results. project root, run:

npx @modelcontextprotocol/inspector \
  uv \
  --directory "$(pwd)" \
  run \
  research-intelligence-mcp

The Inspector should open in your browser.

Then: Connect to MCP Server Open the Tools tab. List tools Select health_check. Run the tool.

Expected structured result:

{
  "status": "healthy",
  "service": "Research Intelligence MCP",
  "server_name": "research-intelligence-mcp",
  "version": "0.1.0",
  "environment": "development",
  "transport": "stdio",
  "timestamp": "2026-07-20T..."
}

Startup flow

main()
  │
  ├── load settings
  ├── configure stderr logging
  ├── build dependency container
  ├── create FastMCP server
  ├── register tools
  └── run stdio transport

MCP Tools

Search Tool

Remote Deployment and Authentication

For the full deployment guide (Docker, AWS ECS, secrets, smoke tests, and the remaining manual AWS steps), see docs/research_intelligence_mcp_deployment_guide.md. The summary below covers the basics.

stdio remains the default local transport and requires no authentication.

For remote deployments (for example, integrating with ResearchMind), the server also supports a streamable-http transport with service-to-service bearer-JWT authentication:

MCP_TRANSPORT=streamable-http
AUTH_ENABLED=true
AUTH_ISSUER=https://auth.researchmind.ai
AUTH_AUDIENCE=research-intelligence-mcp
AUTH_JWKS_URL=https://auth.researchmind.ai/.well-known/jwks.json

See docs/research_intelligence_mcp_authentication.md for the full architecture, docs/research_intelligence_mcp_authentication_testing.md for a verified step-by-step guide to testing it locally, and .env.example for every AUTH_* and MCP_* setting.

On streamable-http, the server also exposes unauthenticated HTTP routes alongside /mcp:

Container

Build and run the production container:

docker build -t research-intelligence-mcp:local .

docker run --rm -p 8000:8000 --env-file .env research-intelligence-mcp:local

The image defaults to MCP_TRANSPORT=streamable-http, binds 0.0.0.0:8000, runs as a non-root user, and ships a container-level HEALTHCHECK against /health. See Dockerfile and .dockerignore.

AWS ECS

Reference (unapplied) task-definition and Service Connect templates, security-group guidance, and a deployment/rollback runbook live in deployment/ecs/README.md.

Deployment Smoke Tests

uv run python deployment/scripts/wait_for_ready.py --base-url http://127.0.0.1:8000
uv run python deployment/scripts/smoke_test.py --base-url http://127.0.0.1:8000

smoke_test.py checks /health, /ready, /metrics, MCP session initialization, tool discovery, and an authenticated health_check + search_papers call. Pass --auth-token when AUTH_ENABLED=true.

Local Observability Stack

Why

/metrics alone is just a text snapshot of counters at the instant you curl it — it can't tell you if arXiv's error rate spiked five minutes ago, whether the cache is actually paying for itself, or whether search_papers got slower after a change. That requires something to scrape it repeatedly, store the history, and let you look at trends instead of one number. docker-compose.yml runs that: the MCP server, Prometheus, and Grafana, wired together.

docker compose up -d --build

In short: Prometheus is the database that remembers metrics over time; Grafana is the window you look through to see them — neither is useful here without the other.

What you can actually do with it

Once traffic flows through (uv run python deployment/scripts/smoke_test.py --base-url http://127.0.0.1:8001, or just use the server), the dashboard's 10 panels let you:

• Watch tool usage live — which of the 7 MCP tools are actually being called, at what rate, and how their p95 latency moves over time (mcp_tool_requests_total, mcp_tool_duration_seconds).

• Catch failures by cause, per tool — a spike in mcp_tool_failures_total{error_type="ValidationError"} vs. {error_type="ProviderTransportError"} tells you immediately whether it's bad input or an upstream outage, without grepping logs.

• See which provider is the bottleneck or the one failing — provider_requests_total / provider_failures_total, broken out by provider (Semantic Scholar vs. arXiv) and operation (search, get_paper, citations, ...), so you don't have to guess which one is slow or rate-limiting you.

• Judge whether caching is worth it — the cache-hit-ratio panel (cache_hits_total / (hits + misses)) shows, per cache (search vs. paper), whether repeat lookups are actually being served from memory.

• Spot HTTP-layer load — request rate by route/status code and in-flight request count, useful for noticing retries, client misbehavior, or load before it becomes a real incident.

• Query anything ad hoc in Prometheus directly (http://127.0.0.1:9090/graph) — the dashboard only covers the panels we pre-built; any of the metric names above can be queried and graphed on the fly with PromQL for a question the dashboard doesn't answer.

This stack is for local development only — it is not deployed as part of the ECS setup above (nothing collects these metrics in production yet; see the "remaining manual tasks" in the deployment guide). See docs/research_intelligence_mcp_deployment_guide.md §8 for teardown and more detail.

License

MIT