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.

Parameter	Type	Required	Default	Description
query	string	Yes	-	The search query
max_results	int	No	5	Maximum results to return

chat_with_knowledge_base

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

Parameter	Type	Required	Default	Description
query	string	Yes	-	Your question
conversation_id	string	No	null	ID to maintain conversation context

start_scrape_job

Scrape a website into the knowledge base.

Parameter	Type	Required	Default	Description
url	string	Yes	-	Starting URL to scrape
max_pages	int	No	50	Maximum pages to scrape
max_depth	int	No	3	How deep to follow links (0 = start page only)
scope	string	No	"HOSTNAME"	SUBPAGES, HOSTNAME, or DOMAIN
include_patterns	list[str]	No	null	Only scrape URLs matching these glob patterns
exclude_patterns	list[str]	No	null	Skip URLs matching these glob patterns
scrape_mode	string	No	"AUTO"	AUTO, FAST (HTTP only), or FULL (browser)
cookies	string	No	null	Cookie string for authenticated sites
force_rescrape	bool	No	false	Re-scrape even if content unchanged

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.

Parameter	Type	Required	Description
job_id	string	Yes	The scrape job ID

list_scrape_jobs

List recent scrape jobs.

Parameter	Type	Required	Default	Description
limit	int	No	10	Maximum jobs to return

upload_document_url

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

Parameter	Type	Required	Description
filename	string	Yes	Name of the file (e.g., 'report.pdf', 'meeting.mp4')

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).

Parameter	Type	Required	Description
filename	string	Yes	Name of the image file (e.g., 'photo.jpg')

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).

Parameter	Type	Required	Description
s3_uri	string	Yes	S3 URI returned by upload_image_url

submit_image

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

Parameter	Type	Required	Default	Description
image_id	string	Yes	-	Image ID from upload_image_url
caption	string	No	null	Primary caption
user_caption	string	No	null	User-provided caption
ai_caption	string	No	null	AI-generated caption

---

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.

Parameter	Type	Required	Default	Description
key_name	string	Yes	-	Proposed key name to check
threshold	float	No	0.8	Similarity threshold (0.0-1.0)

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

Variable	Required	Description
RAGSTACK_GRAPHQL_ENDPOINT	Yes	Your RAGStack GraphQL API URL
RAGSTACK_API_KEY	Yes	Your RAGStack API key

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