Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

Update MCP README: clarify usage & quickstart

Edwin Jose1c05abfd0562
diff --git a/sdks/mcp/README.md b/sdks/mcp/README.md
index ab95550bd..b4b1553cd 100644
--- a/sdks/mcp/README.md
+++ b/sdks/mcp/README.md
@@ -1,99 +1,99 @@
# OpenRAG MCP Server
-An MCP (Model Context Protocol) server that exposes OpenRAG capabilities to AI assistants like Claude Desktop and Cursor.
+An [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that exposes your OpenRAG knowledge base to AI assistants. It lets MCP-compatible apps like Cursor, Claude Desktop, and IBM Watson Orchestrate use OpenRAG’s RAG capabilities (chat, search, settings) over a standard protocol—no custom integrations per platform.
-## Features
+---
-- **Chat** - RAG-enhanced conversations with your knowledge base
-- **Search** - Semantic search over your documents
-- **Document Management** - Ingest files/URLs and manage your knowledge base
+## What is OpenRAG MCP?
-## Available Tools
-
-| Tool | Description |
-|:-----|:------------|
-| `openrag_chat` | Send a message and get a RAG-enhanced response |
-| `openrag_search` | Semantic search over the knowledge base |
-| `openrag_ingest_file` | Ingest a local file into the knowledge base |
-| `openrag_ingest_url` | Ingest content from a URL |
-| `openrag_list_documents` | List documents in the knowledge base |
-| `openrag_delete_document` | Delete a document from the knowledge base |
-
-## Prerequisites
+OpenRAG MCP is a **connectivity layer** between your OpenRAG instance and AI applications. The host app (e.g. Cursor or Claude Desktop) runs the MCP server as a subprocess and talks to it over stdio using JSON-RPC. The server then calls your OpenRAG API with your API key. Your knowledge base stays the single source of truth; all connected apps get the same RAG-backed chat and search.
-1. A running OpenRAG instance
-2. An OpenRAG API key (create one in Settings → API Keys)
-3. Python 3.10+ with `uv` installed
+---
-## Build and run locally
+## Quick Start
-To use the **latest MCP code** (including settings and models tools), run from source. Do **not** install the MCP package if you want local edits to apply.
+Run the server with **uvx** (no local install required; requires Python 3.10+ and [uv](https://docs.astral.sh/uv/)):
-### What to build (in order)
+```bash
+uvx openrag-mcp
+```
-| Step | What | Command | Required for |
-|------|------|---------|--------------|
-| 1 | OpenRAG backend | Run your OpenRAG app (e.g. frontend + API) | All tools |
-| 2 | MCP from source | `cd sdks/mcp && uv sync` | All tools; no wheel needed |
-| 3 | (Optional) SDK from repo | `cd sdks/python && uv pip install -e .` | Only for latest chat/search/documents SDK |
+Set required environment variables first (or pass them via your MCP client config):
-**Settings and models tools** (`openrag_get_settings`, `openrag_update_settings`, `openrag_list_models`) use direct HTTP and do **not** require the SDK. Chat, search, and document tools use the SDK (PyPI version is fine unless you need unreleased SDK changes).
+```bash
+export OPENRAG_URL="https://your-openrag-instance.com"
+export OPENRAG_API_KEY="orag_your_api_key"
+uvx openrag-mcp
+```
-### Run the MCP from source
+To pin a version:
```bash
-cd sdks/mcp
-uv sync
-export OPENRAG_URL="http://localhost:3000"
-export OPENRAG_API_KEY="orag_your_api_key"
-uv run openrag-mcp
+uvx --from openrag-mcp==0.2.1 openrag-mcp
```
-### Cursor: use repo path so it runs your code
+### Prerequisites
-In `~/.cursor/mcp.json`, set `--directory` to your **actual repo path** so Cursor runs the MCP from source, not an installed package:
+- Python 3.10+
+- A running OpenRAG instance
+- An OpenRAG API key (create one in **Settings → API Keys** in OpenRAG)
+- `uv` installed (for `uvx`)
-```json
-"args": ["run", "--directory", "/Users/edwin.jose/Documents/openrag/sdks/mcp", "openrag-mcp"]
-```
+---
-If you previously installed the MCP (`pip install openrag-mcp` or installed a wheel), **uninstall it** so Cursor uses the repo:
+## Available Tools
-```bash
-uv pip uninstall openrag-mcp
-```
+These tools are currently exposed by the server:
-Then restart Cursor.
+| Tool | Description |
+|:-----|:------------|
+| `openrag_chat` | Send a message and get a RAG-enhanced response. Optional: `chat_id`, `filter_id`, `limit`, `score_threshold`. |
+| `openrag_search` | Semantic search over the knowledge base. Optional: `limit`, `score_threshold`, `filter_id`, `data_sources`, `document_types`. |
+| `openrag_get_settings` | Get current OpenRAG configuration (LLM, embeddings, chunk settings, system prompt, etc.). |
+| `openrag_update_settings` | Update OpenRAG configuration (LLM model, embedding model, chunk size/overlap, system prompt, table structure, OCR, picture descriptions). |
+| `openrag_list_models` | List available language and embedding models for a provider (`openai`, `anthropic`, `ollama`, `watsonx`). |
-## Installation
+### Coming later (document tools)
-### Option 1: Run from Source (Recommended for Development)
+Document ingestion and management tools (`openrag_ingest_file`, `openrag_ingest_url`, `openrag_delete_document`, `openrag_get_task_status`, `openrag_wait_for_task`) are implemented but not yet registered in this server; they will be enabled in a future release.
-```bash
-cd openrag/sdks/mcp
-uv sync
-```
+---
-Use `uv run openrag-mcp` from that directory, or point Cursor/Claude `--directory` to this path.
+## Environment Variables
-### Option 2: Install from GitHub
+| Variable | Description | Required | Default |
+|:---------|:------------|:--------:|:--------|
+| `OPENRAG_API_KEY` | Your OpenRAG API key | Yes | — |
+| `OPENRAG_URL` | Base URL of your OpenRAG instance | No | `http://localhost:3000` |
-```bash
-pip install "openrag-mcp @ git+https://github.com/your-org/openrag.git#subdirectory=sdks/mcp"
-```
+These must be set in the environment when the MCP server runs (e.g. in the `env` block of your MCP client config).
-## Configuration
+---
-The MCP server requires two environment variables:
+## How to Use
-| Variable | Description | Default |
-|:---------|:------------|:--------|
-| `OPENRAG_URL` | URL of your OpenRAG instance | `http://localhost:3000` |
-| `OPENRAG_API_KEY` | Your OpenRAG API key | (required) |
+### Cursor
+
+**Config file:** `~/.cursor/mcp.json`
+
+```json
+{
+ "mcpServers": {
+ "openrag": {
+ "command": "uvx",
+ "args": ["openrag-mcp"],
+ "env": {
+ "OPENRAG_URL": "https://your-openrag-instance.com",
+ "OPENRAG_API_KEY": "orag_your_api_key_here"
+ }
+ }
+ }
+}
+```
-## Usage with Claude Desktop
+Restart Cursor after changing the config.
-Add this to your Claude Desktop configuration file:
+### Claude Desktop
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
@@ -102,13 +102,8 @@ Add this to your Claude Desktop configuration file:
{
"mcpServers": {
"openrag": {
- "command": "uv",
- "args": [
- "run",
- "--directory",
- "/path/to/openrag/sdks/mcp",
- "openrag-mcp"
- ],
+ "command": "uvx",
+ "args": ["openrag-mcp"],
"env": {
"OPENRAG_URL": "https://your-openrag-instance.com",
"OPENRAG_API_KEY": "orag_your_api_key_here"
@@ -118,13 +113,37 @@ Add this to your Claude Desktop configuration file:
}
```
-**Important:** Replace `/path/to/openrag` with the actual path to your OpenRAG repository.
+Restart Claude Desktop after editing the file.
+
+---
-## Usage with Cursor
+## Run from source (development)
-Add this to your Cursor MCP configuration:
+To use the **latest MCP code** from the repo (including settings and models tools), run from source. Do **not** install the package if you want local edits to apply.
-**Location:** `~/.cursor/mcp.json`
+### Steps
+
+| Step | What | Command | Required for |
+|------|------|---------|---------------|
+| 1 | OpenRAG backend | Run your OpenRAG app (e.g. frontend + API) | All tools |
+| 2 | MCP from source | `cd sdks/mcp && uv sync` | All tools; no wheel needed |
+| 3 | (Optional) SDK from repo | `cd sdks/python && uv pip install -e .` | Only if you need unreleased chat/search SDK changes |
+
+Settings and models tools (`openrag_get_settings`, `openrag_update_settings`, `openrag_list_models`) use direct HTTP. Chat and search use the OpenRAG SDK (PyPI version is fine unless you need unreleased SDK changes).
+
+### Run the MCP from source
+
+```bash
+cd sdks/mcp
+uv sync
+export OPENRAG_URL="http://localhost:3000"
+export OPENRAG_API_KEY="orag_your_api_key"
+uv run openrag-mcp
+```
+
+### Cursor: use repo path so it runs your code
+
+In `~/.cursor/mcp.json`, set `--directory` to your **actual repo path** so Cursor runs the MCP from source:
```json
{
@@ -146,59 +165,63 @@ Add this to your Cursor MCP configuration:
}
```
-## Testing
+Replace `/path/to/openrag` with your real path (e.g. `/Users/edwin.jose/Documents/openrag`).
-You can test the MCP server locally:
+If you previously installed the MCP (`pip install openrag-mcp` or a wheel), uninstall it so Cursor uses the repo:
```bash
-cd /path/to/openrag/sdks/mcp
+uv pip uninstall openrag-mcp
+```
-# Set environment variables
-export OPENRAG_URL="http://localhost:3000"
-export OPENRAG_API_KEY="orag_your_test_key"
+Then restart Cursor.
+
+---
+
+## Use cases and benefits
+
+- **One integration, many apps** – Same MCP server works with Cursor, Claude Desktop, Watson Orchestrate, and any MCP client.
+- **RAG in the loop** – Chat and search are grounded in your OpenRAG knowledge base, with optional filters and scoring.
+- **Agent-friendly** – Agents can call OpenRAG for answers, list models, and read/update settings without custom APIs.
+- **Lightweight** – No extra service to deploy; the host app spawns the server as a subprocess and talks over stdio.
+- **Secure** – Only clients that have your `OPENRAG_API_KEY` (via env) can use the server to access OpenRAG.
+
+**Example scenarios:** Query internal docs and runbooks from your IDE; power support bots with your product docs; search and summarize across ingested documents; automate workflows that need RAG (when document tools are enabled).
+
+---
-# Run the server (it will wait for MCP protocol input)
-uv run openrag-mcp
-```
-## Example Prompts
+## Example prompts
-Once configured, you can ask Claude or Cursor things like:
+Once the server is configured, you can ask the AI to:
-- *"Search my knowledge base for information about machine learning"*
-- *"What documents do I have in OpenRAG?"*
-- *"Chat with OpenRAG about the quarterly report"*
-- *"Ingest this PDF: /path/to/document.pdf"*
-- *"Delete the file 'old_report.pdf' from my knowledge base"*
+- *"Search my knowledge base for authentication best practices"*
+- *"Chat with OpenRAG about the Q4 roadmap"*
+- *"What are the current OpenRAG settings?"*
+- *"List available models for the openai provider"*
+- *"Update OpenRAG to use chunk size 512"*
+
+---
## Troubleshooting
### "OPENRAG_API_KEY environment variable is required"
-Make sure you've set the `OPENRAG_API_KEY` in the `env` section of your MCP configuration.
+Set `OPENRAG_API_KEY` in the `env` section of your MCP config (Cursor or Claude Desktop). The server reads it at startup.
-### "Connection refused" errors
+### "Connection refused" or network errors
-1. Check that your OpenRAG instance is running
-2. Verify the `OPENRAG_URL` is correct
-3. Ensure there are no firewall rules blocking the connection
+1. Confirm your OpenRAG instance is running and reachable.
+2. Check `OPENRAG_URL` (no trailing slash; include `https://` if applicable).
+3. Ensure no firewall or proxy is blocking the client machine from reaching OpenRAG.
-### Tools not appearing in Claude Desktop
+### Tools not appearing
-1. Restart Claude Desktop after updating the configuration
-2. Check the Claude Desktop logs for error messages
-3. Verify the path to the `openrag/sdks/mcp` directory is correct
+1. Restart the host app (Cursor or Claude Desktop) after changing the MCP config.
+2. Check the app’s MCP/log output for errors (e.g. wrong `command`/`args` or missing `uv`/`uvx`).
+3. If using "run from source", ensure `args` includes `--directory` and the correct path to `sdks/mcp`.
-## Architecture
-
-```
-┌─────────────────┐ stdio ┌─────────────────┐ HTTPS ┌─────────────────┐
-│ Claude Desktop │◄─────────────────►│ openrag-mcp │◄──────────────────►│ OpenRAG │
-│ or Cursor │ JSON-RPC (MCP) │ (subprocess) │ X-API-Key auth │ deployment │
-└─────────────────┘ └─────────────────┘ └─────────────────┘
-```
+---
## License
Apache 2.0 - See [LICENSE](../../LICENSE) for details.
-