RAGStack MCP Server

MCP (Model Context Protocol) server for RAGStack knowledge bases. Enables AI assistants to search, chat, upload documents/media, and scrape your knowledge base.

Installation

# Using uvx (recommended - no install needed)
uvx ragstack-mcp
 
# Or install globally
pip install ragstack-mcp

Configuration

Get your GraphQL endpoint and API key from the RAGStack dashboard: Settings → API Key

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ragstack-kb": {
      "command": "uvx",
      "args": ["ragstack-mcp"],
      "env": {
        "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",
        "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"
      }
    }
  }
}

Amazon Q CLI

Edit ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "ragstack-kb": {
      "command": "uvx",
      "args": ["ragstack-mcp"],
      "env": {
        "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",
        "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Open Settings → MCP Servers → Add Server, or edit .cursor/mcp.json:

{
  "ragstack-kb": {
    "command": "uvx",
    "args": ["ragstack-mcp"],
    "env": {
      "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",
      "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"
    }
  }
}

VS Code + Cline

Edit .vscode/cline_mcp_settings.json:

{
  "mcpServers": {
    "ragstack-kb": {
      "command": "uvx",
      "args": ["ragstack-mcp"],
      "env": {
        "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",
        "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"
      }
    }
  }
}

VS Code + Continue

Edit ~/.continue/config.json, add to mcpServers array:

{
  "mcpServers": [
    {
      "name": "ragstack-kb",
      "command": "uvx",
      "args": ["ragstack-mcp"],
      "env": {
        "RAGSTACK_GRAPHQL_ENDPOINT": "https://xxx.appsync-api.us-east-1.amazonaws.com/graphql",
        "RAGSTACK_API_KEY": "da2-xxxxxxxxxxxx"
      }
    }
  ]
}

Available Tools

search_knowledge_base

Search for relevant documents in the knowledge base.

chat_with_knowledge_base

Ask questions and get AI-generated answers with source citations.

start_scrape_job

Scrape a website into the knowledge base.

Scope values:

• SUBPAGES - Only URLs under the starting path
• HOSTNAME - All pages on the same subdomain
• DOMAIN - All subdomains of the domain

Scrape mode values:

• AUTO - Try fast mode, fall back to full for SPAs
• FAST - HTTP only, faster but may miss JavaScript content
• FULL - Uses headless browser, handles all JavaScript

get_scrape_job_status

Check the status of a scrape job.

list_scrape_jobs

List recent scrape jobs.

upload_document_url

Get a presigned URL to upload a document or media file.

Supported formats:

• Documents: PDF, DOCX, XLSX, HTML, TXT, CSV, JSON, XML, EML, EPUB, Markdown
• Images: JPG, PNG, GIF, WebP, AVIF, BMP, TIFF
• Video: MP4, WebM
• Audio: MP3, WAV, M4A, OGG, FLAC

Video/audio files are transcribed using AWS Transcribe and segmented for search.

upload_image_url

Get a presigned URL to upload an image (step 1 of image upload workflow).

Supported formats: JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF

generate_image_caption

Generate an AI caption for an uploaded image using a vision model (step 2, optional).

submit_image

Finalize an image upload and trigger indexing (step 3).

Configuration Tools (Read-Only)

get_configuration

Get all current RAGStack configuration settings organized by category.

Returns settings for:

• Chat: Models, quotas, system prompt, document access
• Metadata Extraction: Enabled, model, mode (auto/manual), max keys
• Query-Time Filtering: Filter generation, multi-slice retrieval settings
• Public Access: Which endpoints allow unauthenticated access
• Document Processing: OCR backend, image caption prompt
• Media Processing: Transcribe language, speaker diarization, segment duration
• Budget: Alert thresholds

Note: Read-only. To modify settings, use the admin dashboard (Cognito auth required).

Metadata Analysis Tools

These tools help understand and optimize metadata extraction and filtering.

get_metadata_stats

Get statistics about metadata keys extracted from documents.

Returns key names, data types, occurrence counts, sample values, and status.

get_filter_examples

Get AI-generated filter examples for metadata-based search queries.

Returns filter patterns with name, description, use case, and JSON filter syntax.

Filter syntax reference:

• Basic operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists
• Logical operators: $and, $or
• Example: {"topic": {"$eq": "genealogy"}}

get_key_library

Get the complete metadata key library with all discovered keys.

Returns all keys available for filtering with data types and sample values.

check_key_similarity

Check if a proposed metadata key is similar to existing keys.

Use this before adding documents with new keys to avoid duplicates.

analyze_metadata

Trigger metadata analysis to discover keys and generate filter examples.

Note: This is a long-running operation (1-2 minutes). It samples up to 1000 vectors and uses LLM analysis.

Run this after ingesting new documents or when filter generation isn't working as expected.

Usage Examples

Once configured, just ask your AI assistant naturally:

Search & Chat:

• "Search my knowledge base for authentication best practices"
• "What does our documentation say about API rate limits?"
• "What was discussed in the team meeting about deadlines?" (searches video/audio transcripts)

Web Scraping:

• "Scrape the React docs at react.dev/reference"
• "Check the status of my scrape job"

Document, Image & Media Upload:

• "Upload a new document called quarterly-report.pdf"
• "Upload this image and generate a caption for it"
• "Upload the meeting recording meeting-2024-01.mp4"

Metadata Analysis:

• "What metadata keys are available for filtering?"
• "Analyze the metadata in my knowledge base"
• "Show me the filter examples"
• "Check if 'author' is similar to any existing keys"

Configuration:

• "What are my current RAGStack settings?"
• "What model is being used for chat?"
• "Is multi-slice retrieval enabled?"
• "What are my quota limits?"
• "What language is configured for transcription?"

Environment Variables

Development

# Clone and install
cd src/ragstack-mcp
uv sync
 
# Run locally
uv run ragstack-mcp
 
# Build package
uv build
 
# Publish to PyPI
uv publish

License

MIT