MCP Server

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

Installation

npm install -g @flowrag/mcp

Or run directly:

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

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-here

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 ./content

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

TIP

local has no extractor — pair it with gemini or bedrock for entity extraction.

AI Assistant Setup

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"]
    }
  }
}

Kiro

Add to your project's mcp.json:

{
  "mcpServers": {
    "flowrag": {
      "command": "npx",
      "args": ["@flowrag/mcp", "--config", "/path/to/flowrag.config.json"]
    }
  }
}

Tools

The MCP server exposes 8 tools that AI assistants can call:

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

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

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

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

Get relations for a specific entity.

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

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

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

Get index statistics. No parameters.

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

Resources

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

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

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.

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.