# BGPT MCP + REST API

**Search scientific papers from Claude, Cursor, any MCP-compatible AI tool, or plain Python.**

BGPT is a remote [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server and traditional JSON/HTTP API that gives AI assistants and Python apps access to a database of scientific papers built from full-text studies. Unlike typical search tools that return titles and abstracts, BGPT extracts **raw experimental data** — methods, results, conclusions, quality scores, sample sizes, limitations, and 25+ metadata fields per paper.

[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
[![npm](https://img.shields.io/npm/v/bgpt-mcp)](https://www.npmjs.com/package/bgpt-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![bgpt-mcp MCP server](https://glama.ai/mcp/servers/connerlambden/bgpt-mcp/badges/score.svg)](https://glama.ai/mcp/servers/connerlambden/bgpt-mcp)

---

## Evidence Demo

If you want to see why BGPT is different from ordinary paper search, start here:

- [`EVIDENCE_DEMO.md`](EVIDENCE_DEMO.md) — a claim-interrogation demo for `GLP-1 alcohol craving`
- [`examples/bgpt_plotly_evidence_dashboard.py`](examples/bgpt_plotly_evidence_dashboard.py) — generate a Plotly HTML dashboard with study methods, samples, limitations, conflicts, data availability, blind spots, and falsifiability prompts
- [`PROMPT_GALLERY.md`](PROMPT_GALLERY.md) — prompts for scientific RAG, literature review agents, and evidence dashboards

The core idea: BGPT helps an AI agent ask **what would weaken this scientific claim?** before it summarizes the literature.

---

## Quick Start

Use BGPT from Python, REST, or an MCP client — no API key required for the free tier (50 free results).

### Option A: Python / REST API

Call the HTTP API directly from any Python script or notebook:

```python
import requests


def search_bgpt(query, num_results=10, days_back=None, api_key=None):
    payload = {"query": query, "num_results": num_results}
    if days_back is not None:
        payload["days_back"] = days_back
    if api_key:
        payload["api_key"] = api_key

    response = requests.post(
        "https://bgpt.pro/api/mcp-search",
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["results"]


papers = search_bgpt("CRISPR delivery neurons", num_results=5)
print(papers[0]["title"])
```

### Option B: Remote MCP Connection

Most modern MCP clients support direct remote connections. BGPT offers two transports:

| Transport | Endpoint |
|-----------|----------|
| **SSE** | `https://bgpt.pro/mcp/sse` |
| **Streamable HTTP** | `https://bgpt.pro/mcp/stream` |

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "bgpt": {
      "url": "https://bgpt.pro/mcp/sse"
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "bgpt": {
      "url": "https://bgpt.pro/mcp/sse"
    }
  }
}
```

**Claude Code** (CLI):
```bash
claude mcp add bgpt --transport sse https://bgpt.pro/mcp/sse
```

**Cline / Roo Code / Windsurf** — same config:
```json
{
  "mcpServers": {
    "bgpt": {
      "url": "https://bgpt.pro/mcp/sse"
    }
  }
}
```

> **Tip:** If your client supports Streamable HTTP, you can use `https://bgpt.pro/mcp/stream` instead.

### Option C: Via npx (for clients that need a local command)

```json
{
  "mcpServers": {
    "bgpt": {
      "command": "npx",
      "args": ["-y", "bgpt-mcp"]
    }
  }
}
```

### Option D: Install globally

```bash
npm install -g bgpt-mcp
```

Then add to your MCP config:
```json
{
  "mcpServers": {
    "bgpt": {
      "command": "bgpt-mcp"
    }
  }
}
```

### Any MCP Client

Connect to either endpoint:

```
SSE:              https://bgpt.pro/mcp/sse
Streamable HTTP:  https://bgpt.pro/mcp/stream
```

That's it. No Docker, no build step.

---

## What You Get

BGPT exposes the same scientific-paper search through an MCP tool and a REST endpoint.

### REST endpoint

`POST https://bgpt.pro/api/mcp-search`

| JSON field | Type | Required | Description |
|------------|------|----------|-------------|
| `query` | string | Yes | Search terms (e.g. "CRISPR gene editing efficiency") |
| `num_results` | integer | No | Number of results to return (1-100, default 10) |
| `days_back` | integer | No | Only return papers published within the last N days |
| `api_key` | string | No | Your Stripe subscription ID for paid access |

### MCP tool

`search_papers`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search terms (e.g. "CRISPR gene editing efficiency") |
| `num_results` | integer | No | Number of results to return (1-100, default 10) |
| `days_back` | integer | No | Only return papers published within the last N days |
| `api_key` | string | No | Your Stripe subscription ID for paid access |

### What comes back

Each paper result includes **25+ fields**, extracted from the full text:

- **Title & DOI** — standard identifiers
- **Methods** — experimental design, techniques used
- **Results** — raw findings, measurements, statistical outcomes
- **Conclusions** — what the authors determined
- **Quality scores** — methodological rigor assessment
- **Sample sizes** — participant/specimen counts
- **Limitations** — acknowledged weaknesses
- **And more** — funding, conflicts of interest, study type, etc.

### Example

Ask your AI assistant:

> "Search for recent papers on CAR-T cell therapy response rates"

BGPT returns structured experimental data your AI can reason over — not just a list of titles.

---

## Pricing

| Tier | Cost | Details |
|------|------|---------|
| **Free** | $0 | 50 free results, no API key needed |
| **Pay-as-you-go** | $0.02/result | Billed per result returned. Get an API key at [bgpt.pro/mcp](https://bgpt.pro/mcp) |

---

## How It Works

```
Your AI Assistant (Claude, Cursor, etc.)
        │
        │  MCP Protocol (SSE or Streamable HTTP)
        ▼
   BGPT MCP / REST API
   https://bgpt.pro/mcp/sse
   https://bgpt.pro/mcp/stream
   https://bgpt.pro/api/mcp-search
        │
        │  search_papers(query, ...)
        ▼
   BGPT Paper Database
   (full-text extracted data)
        │
        ▼
   Structured Results
   (methods, results, quality scores, 25+ fields)
```

BGPT is a **hosted remote service** — your MCP client connects via SSE or Streamable HTTP, or your app calls the REST endpoint directly. No Docker, scraping, or local index required.

---

## Use Cases

- **Literature reviews** — Ask your AI to survey a topic with real experimental data
- **Python notebooks** — Pull recent paper evidence into analysis workflows with one HTTP call
- **Evidence synthesis** — Ground AI responses in actual study findings
- **Research assistance** — Find papers by methodology, outcome, or recency
- **Fact-checking** — Verify claims against published experimental results
- **Grant writing** — Quickly gather supporting evidence for proposals

---

## Configuration Reference

### Server Details

| Field | Value |
|-------|-------|
| Protocol | MCP (Model Context Protocol) |
| Transport | SSE (Server-Sent Events) or Streamable HTTP |
| SSE Endpoint | `https://bgpt.pro/mcp/sse` |
| Streamable HTTP Endpoint | `https://bgpt.pro/mcp/stream` |
| REST Endpoint | `https://bgpt.pro/api/mcp-search` |
| Authentication | None required (free tier) / Stripe API key (paid) |

### Full MCP Client Config

```json
{
  "mcpServers": {
    "bgpt": {
      "url": "https://bgpt.pro/mcp/sse"
    }
  }
}
```

---

## Related MCP

From the same author — news/markets bias scoring on one side, structured scientific evidence on the other:

- [Helium MCP](https://github.com/connerlambden/helium-mcp) — 37-dimensional news bias scoring, market data, ML options pricing ([demo](https://connerlambden.github.io/helium-news-explorer/))
- [helium-mcp-cookbook](https://github.com/connerlambden/helium-mcp-cookbook) — runnable Python recipes for Helium's REST surface

---

## Listed On

BGPT is indexed on several API and MCP directories (helps discovery; links are dofollow where noted):

- [bio.tools](https://bio.tools/bgpt) — life-science software registry (`biotools:bgpt`)
- [CLIRank](https://clirank.dev/score/bgpt-api) — API quality score
- [Glama MCP](https://glama.ai/mcp/servers/@connerlambden/bgpt-mcp) — MCP server directory
- [Postman API Network](https://www.postman.com/connerlambden-5212589/bgpt-scientific-paper-search-api/overview) — runnable collection
- [Smithery](https://smithery.ai/server/bgpt/bgpt-mcp) — MCP registry
- [cursor.directory](https://cursor.directory/mcp/bgpt-mcp-api) — Cursor MCP listing

---

## Documentation

Full documentation, FAQ, and setup guides: **[bgpt.pro/mcp](https://bgpt.pro/mcp/)**

OpenAPI spec for the REST endpoint: **[`openapi.yaml`](openapi.yaml)**

Additional REST discovery assets:

- **[`apis.json`](apis.json)** — machine-readable API discovery metadata
- **[`llms.txt`](llms.txt)** — AI-crawler and agent-friendly product context
- **[`AGENTS.md`](AGENTS.md)** — integration guidance for AI agents
- **[`USE_CASES.md`](USE_CASES.md)** — RAG, systematic review, notebook, and dashboard use cases
- **[`PROMPT_GALLERY.md`](PROMPT_GALLERY.md)** — ready-to-use prompts for scientific RAG, agents, integrity checks, and visual demos
- **[`CITATION.cff`](CITATION.cff)** and **[`codemeta.json`](codemeta.json)** — research-software metadata
- **[`examples/bgpt_rest_python.py`](examples/bgpt_rest_python.py)** — Python `requests` example
- **[`examples/bgpt_rest_javascript.mjs`](examples/bgpt_rest_javascript.mjs)** — JavaScript `fetch` example
- **[`examples/bgpt_rest_curl.sh`](examples/bgpt_rest_curl.sh)** — cURL example
- **[`examples/bgpt_plotly_evidence_dashboard.py`](examples/bgpt_plotly_evidence_dashboard.py)** — Plotly evidence dashboard demo
- **[`examples/postman_collection.json`](examples/postman_collection.json)** — importable Postman collection

---

## Support

- **Email:** [contact@bgpt.pro](mailto:contact@bgpt.pro)
- **Issues:** [GitHub Issues](../../issues)
- **API Key / Billing:** [bgpt.pro/mcp](https://bgpt.pro/mcp)

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on reporting bugs, requesting features, and contributing.

---

## License

This repository (documentation, examples, and configuration files) is licensed under the [MIT License](LICENSE).

The BGPT MCP API service itself is operated by BGPT and subject to its own [terms of service](https://bgpt.pro/mcp/) and [Privacy Policy](PRIVACY_POLICY.md).