MCP Documentation

Getting Started with the NobleBlocks MCP

The NobleBlocks MCP server enables AI assistants like Claude, Cursor, VS Code Copilot, and other MCP-compatible clients to search over 290 million academic papers directly from the conversation.

Getting Started

NobleBlocks MCP is distributed as a Python package on PyPI. Connect your preferred client below — you'll be searching in under 2 minutes.

Prerequisite: Python 3.10+

Mac: brew install python or download from python.org. Windows: download from python.org — check "Add to PATH" during install.

Free NobleBlocks account required

Create a free account to get your API key. Go to Settings → API Keys to generate one. Free tier includes 100 queries/day.

Connect Your Client

Claude Desktop

Open Claude Desktop → click the gear icon (bottom-left) → Developer → Edit Config
Paste the config below into the file and save
Restart Claude Desktop
Ask: "Search for papers on CRISPR gene therapy"

{
  "mcpServers": {
    "nobleblocks": {
      "command": "uvx",
      "args": ["nobleblocks-mcp"],
      "env": {
        "NOBLEBLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Open Cursor → Settings (⌘+, on Mac, Ctrl+, on Windows)
Go to MCP → click "Add new MCP server"
Paste the config below
Restart Cursor — in Composer or Chat, ask: "Find papers on transformer architectures"

{
  "mcpServers": {
    "nobleblocks": {
      "command": "uvx",
      "args": ["nobleblocks-mcp"],
      "env": {
        "NOBLEBLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Open VS Code → Settings (⌘+, on Mac, Ctrl+, on Windows)
Search for "mcp" → click "Edit in settings.json"
Add the config below to your settings.json
Restart VS Code — in Copilot Chat, ask: "Search for papers on machine learning"

{
  "mcp": {
    "servers": {
      "nobleblocks": {
        "command": "uvx",
        "args": ["nobleblocks-mcp"],
        "env": {
          "NOBLEBLOCKS_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Windsurf

Open Windsurf → Settings → MCP
Click "Add Server" or edit the MCP config file
Paste the config below
Restart Windsurf and ask Cascade: "Find recent papers on protein folding"

{
  "mcpServers": {
    "nobleblocks": {
      "command": "uvx",
      "args": ["nobleblocks-mcp"],
      "env": {
        "NOBLEBLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cline

Open Cline in VS Code → click the gear icon → MCP Servers
Click "Add MCP Server"
Paste the config below
Ask Cline: "Search for papers on neural architecture search"

{
  "mcpServers": {
    "nobleblocks": {
      "command": "uvx",
      "args": ["nobleblocks-mcp"],
      "env": {
        "NOBLEBLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client that supports stdio transport can connect using the uvx nobleblocks-mcp command. Set the NOBLEBLOCKS_API_KEY environment variable for authentication.

ChatGPT (Custom GPT)

ChatGPT doesn't natively support MCP, but you can use NobleBlocks as a Custom GPT action. See the ChatGPT setup guide on GitHub.

Verify Your Connection

Try asking your AI assistant:

"What does the research say about the effects of exercise on depression?"

You should see results citing specific papers with titles, authors, publication years, citation counts, and direct links.

Available Tools

The NobleBlocks MCP server exposes 5 tools that your AI assistant can call:

search_papers

Search across 290M+ papers from PubMed, OpenAlex, Semantic Scholar, arXiv, EuropePMC, Crossref, and more.

Parameter	Type	Required	Description
query	string	Yes	The research question or topic to search for
limit	integer	No	Maximum results to return (default: 10, max: 50)
year_min	integer	No	Exclude papers published before this year
year_max	integer	No	Exclude papers published after this year

get_paper

Get full details for any paper — title, authors, abstract, citation count, and PDF link. Works with DOI, PMID, or arXiv ID.

Parameter	Type	Required	Description
paperId	string	Yes	DOI, PMID, arXiv ID, or NobleBlocks paper ID

find_similar

Find papers related by meaning, not just matching words. Discovers work you might miss with keyword search alone.

Parameter	Type	Required	Description
query	string	Yes	Description of the research topic or a paper title
limit	integer	No	Number of similar papers to return (default: 10)

get_citation_graph

See what a paper cites and who cites it. Trace the full research lineage to understand how ideas connect.

Parameter	Type	Required	Description
paperId	string	Yes	DOI, PMID, or paper ID to get citation network for

create_literature_review

Ask a research question and get a written summary of what the science says — with references to real published papers. Uses AI credits from your NobleBlocks account.

Parameter	Type	Required	Description
query	string	Yes	Research question for the literature review
maxPapers	integer	No	Maximum papers to include (default: 20)

Example Prompts

•"What does the research say about the effectiveness of remote work on productivity?"
•"Find recent papers on mRNA vaccine stability published after 2022"
•"Get the citation graph for DOI 10.1038/s41586-023-06004-3"
•"Create a literature review on mindfulness and anxiety in college students"
•"Find papers similar to: transformer architectures for protein folding prediction"

Plans & Access

Your results depend on your NobleBlocks plan, not your AI subscription (Claude Pro, ChatGPT Plus, etc. have no effect on NobleBlocks results).

Plan	Results per query	Queries/day	Features
Free	10	100	All 5 tools, 15+ databases
Pro	50	5,000	All 5 tools, 15+ databases, priority search, literature reviews

Create a free account at nobleblocks.com/auth/register. Upgrade at nobleblocks.com/pricing.

Troubleshooting

Server shows failed or no tools appear

Verify Python 3.10+ is installed: python3 --version
Verify uvx works: uvx nobleblocks-mcp --help
Check your API key is set correctly in the config
Restart your client completely (not just reconnect)

No results found

Try broadening your search query. Use specific academic terminology rather than casual language. Remove year filters if set.

Rate limit exceeded (429 error)

Wait a few moments before searching again. Free tier allows 100 queries/day. If you need more, upgrade to Pro at nobleblocks.com/pricing.

Connection timeout

The MCP server connects to NobleBlocks APIs over HTTPS. Ensure you have internet access and that your firewall isn't blocking outbound HTTPS connections to nobleblocks.com.

"uvx: command not found"

Install uv first: pip install uv or brew install uv (Mac). Alternatively, use pip install nobleblocks-mcp and replace uvx nobleblocks-mcp with nobleblocks-mcp in your config.

Security

Authentication: API keys are passed via environment variables, never in prompts or URLs. Keys are sent as Bearer tokens over HTTPS/TLS.
Input sanitization: All inputs are validated, length-limited, and checked for injection patterns before being sent to the API.
Data handling: Search queries are sent to the NobleBlocks API over HTTPS. Results contain publicly available academic paper metadata (titles, abstracts, authors). No personal data is stored from MCP requests.
Audit logging: Tool calls are logged locally (tool name, timing, result count) for debugging. No query content is sent to third parties.
Rate limiting: In-memory sliding-window rate limiter prevents abuse (60/min, 100/day free, 5000/day pro).

Supported Platforms

Platform	Transport	Status
Claude Desktop	stdio (local)	Supported
Cursor	stdio (local)	Supported
VS Code (Copilot)	stdio (local)	Supported
Windsurf	stdio (local)	Supported
Cline	stdio (local)	Supported
Claude Web (claude.ai)	Remote HTTP	Coming soon
ChatGPT	Custom GPT action	Supported