MCP Server
@flowrag/mcp exposes your FlowRAG knowledge base to AI assistants via the Model Context Protocol.
Installation
Section titled “Installation”npm install -g @flowrag/mcpOr run directly:
npx @flowrag/mcp --data ./data --docs ./contentConfiguration
Section titled “Configuration”Create flowrag.config.json in your project root:
{ "data": "./data", "docs": "./content", "schema": { "entityTypes": ["SERVICE", "DATABASE", "PROTOCOL"], "relationTypes": ["USES", "PRODUCES", "CONSUMES"] }, "embedder": { "provider": "local" }, "extractor": { "provider": "gemini" }}API keys go in a .env file (auto-loaded on startup):
GEMINI_API_KEY=your-key-hereCLI Flags
Section titled “CLI Flags”| Flag | Description | Default |
|---|---|---|
--config <path> |
Config file path | ./flowrag.config.json |
--data <path> |
Data directory | ./data |
--docs <path> |
Documents directory | — |
Priority: CLI flags > config file > defaults. For the simplest case, no config file is needed:
npx @flowrag/mcp --data ./data --docs ./contentProvider Defaults
Section titled “Provider Defaults”| Provider | Embedder Model | Extractor Model |
|---|---|---|
local |
Xenova/e5-small-v2 |
— (not available) |
gemini |
gemini-embedding-001 |
gemini-3-flash-preview |
bedrock |
amazon.titan-embed-text-v2:0 |
anthropic.claude-haiku-4-5-20251001-v1:0 |
AI Assistant Setup
Section titled “AI Assistant Setup”Claude Desktop
Section titled “Claude Desktop”Add to your Claude Desktop config (claude_desktop_config.json):
{ "mcpServers": { "flowrag": { "command": "npx", "args": ["@flowrag/mcp", "--config", "/path/to/flowrag.config.json"] } }}Add to your project’s mcp.json:
{ "mcpServers": { "flowrag": { "command": "npx", "args": ["@flowrag/mcp", "--config", "/path/to/flowrag.config.json"] } }}The MCP server exposes 8 tools that AI assistants can call:
flowrag_index
Section titled “flowrag_index”Index documents into the knowledge base.
| Parameter | Type | Description |
|---|---|---|
force |
boolean? |
Re-index all documents, ignore hashes |
Uses the docs path from config. Unchanged documents are skipped automatically via SHA-256 hashing.
flowrag_search
Section titled “flowrag_search”Search with dual retrieval (vector + graph).
| Parameter | Type | Description |
|---|---|---|
query |
string |
Search query (required) |
mode |
string? |
hybrid, local, global, naive (default: hybrid) |
limit |
number? |
Max results (default: 5) |
flowrag_search_entities
Section titled “flowrag_search_entities”Semantic search for entities in the knowledge graph by description similarity.
| Parameter | Type | Description |
|---|---|---|
query |
string |
Search query (required) |
limit |
number? |
Max results (default: 10) |
type |
string? |
Filter by entity type |
Unlike flowrag_entities (which does exact/substring matching), this tool uses vector similarity to find entities by meaning. For example, “the service that handles login” can find an entity named “Auth Service”.
flowrag_entities
Section titled “flowrag_entities”List or filter entities in the knowledge graph.
| Parameter | Type | Description |
|---|---|---|
type |
string? |
Filter by entity type (e.g. SERVICE) |
query |
string? |
Filter by name/description substring |
limit |
number? |
Max results (default: 20) |
flowrag_relations
Section titled “flowrag_relations”Get relations for a specific entity.
| Parameter | Type | Description |
|---|---|---|
entity |
string |
Entity name (required) |
direction |
string? |
in, out, both (default: both) |
flowrag_trace
Section titled “flowrag_trace”Trace data flow upstream or downstream from an entity.
| Parameter | Type | Description |
|---|---|---|
entity |
string |
Entity name (required) |
direction |
string |
upstream or downstream (required) |
flowrag_path
Section titled “flowrag_path”Find the shortest path between two entities.
| Parameter | Type | Description |
|---|---|---|
from |
string |
Source entity name (required) |
to |
string |
Target entity name (required) |
maxDepth |
number? |
Max traversal depth (default: 5) |
flowrag_stats
Section titled “flowrag_stats”Get index statistics. No parameters.
Returns document, chunk, entity, relation, and vector counts.
Resources
Section titled “Resources”flowrag://schema
Section titled “flowrag://schema”Exposes the current schema definition as JSON, so the AI assistant knows what entity types, relation types, and custom fields are available.
Config Change Detection
Section titled “Config Change Detection”After indexing, a flowrag.meta.json file is saved in the data directory with embedder, extractor, and schema info.
On startup, the server compares the current config with this metadata:
| Change | Severity | Effect |
|---|---|---|
| Embedder changed | Breaking | Embeddings are incompatible — re-index required |
| Schema changed | Minor | New types apply on next indexing |
| Extractor changed | Minor | New extractions may differ |
Entity Resolution
Section titled “Entity Resolution”Tools that accept entity names (flowrag_relations, flowrag_trace, flowrag_path) resolve names using:
- Exact match (entity ID)
- Case-insensitive match
- Substring match
- Error if no match found
This means you can type auth and it will find AuthService.
Remote / HTTP Mode
Section titled “Remote / HTTP Mode”The MCP server can also run as a centralized HTTP server for team use:
{ "transport": "http", "port": 3000, "auth": { "token": "${FLOWRAG_AUTH_TOKEN}" }, "storage": { "kv": { "provider": "redis", "url": "redis://redis.internal:6379" }, "vector": { "provider": "opensearch", "node": "https://os:9200", "dimensions": 1024 }, "graph": { "provider": "opensearch", "node": "https://os:9200" } }}Clients connect via URL instead of spawning a local process:
{ "mcpServers": { "flowrag": { "url": "https://flowrag.company.com/mcp", "headers": { "Authorization": "Bearer ${FLOWRAG_TOKEN}" } } }}See Remote MCP Server for full deployment guide including Docker and Fargate.