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.mdindex 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 │-└─────────────────┘ └─────────────────┘ └─────────────────┘-```+---## LicenseApache 2.0 - See [LICENSE](../../LICENSE) for details.-