Skip to content

MCP Server

@flowrag/mcp exposes your FlowRAG knowledge base to AI assistants via the Model Context Protocol.

Terminal window
npm install -g @flowrag/mcp

Or run directly:

Terminal window
npx @flowrag/mcp --data ./data --docs ./content

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

Terminal window
GEMINI_API_KEY=your-key-here
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:

Terminal window
npx @flowrag/mcp --data ./data --docs ./content
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

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:

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.

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)

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

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)

Get relations for a specific entity.

Parameter Type Description
entity string Entity name (required)
direction string? in, out, both (default: both)

Trace data flow upstream or downstream from an entity.

Parameter Type Description
entity string Entity name (required)
direction string upstream or downstream (required)

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)

Get index statistics. No parameters.

Returns document, chunk, entity, relation, and vector counts.

Exposes the current schema definition as JSON, so the AI assistant knows what entity types, relation types, and custom fields are available.

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

Tools that accept entity names (flowrag_relations, flowrag_trace, flowrag_path) resolve names using:

  1. Exact match (entity ID)
  2. Case-insensitive match
  3. Substring match
  4. Error if no match found

This means you can type auth and it will find AuthService.

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.