LLM Connections

Connect MDDB to AI agents and LLM tools for RAG (Retrieval-Augmented Generation) and knowledge base workflows.

→ Full MCP Server Configuration (env vars, API keys, rate limits, logging)

Overview

MDDB provides multiple integration paths:

Domain Configuration

Set MDDB_MCP_DOMAIN to your server hostname. The Panel's LLM Connections page reads this value and pre-fills it in the domain field — all generated configs use it automatically.

docker run -d -p 11023:11023 -p 9000:9000 \ -e MDDB_MCP_DOMAIN=myserver.com \ tradik/mddb:latest MDDB_MCP_DOMAIN=myserver.com ./mddbd

You can also change the domain directly in the Panel — the input field is above the config tabs on the LLM Connections page.

MCP Streamable HTTP Transport (Recommended)

MDDB implements the Streamable HTTP transport from MCP spec 2025-11-25. A single /mcp endpoint handles all communication — simpler than the legacy SSE transport.

How It Works

1. Client sends POST /mcp with JSON-RPC request
2. Server responds with JSON (or SSE stream for server-initiated messages via GET /mcp)
3. Session management via MCP-Session-Id header (assigned at initialize)
4. Client can DELETE /mcp to terminate the session

Example

curl -X POST http://localhost:9000/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \ -D - curl -X POST http://localhost:9000/mcp \ -H "Content-Type: application/json" \ -H "MCP-Session-Id: a9f9de82af6938bc..." \ -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' curl -X POST http://localhost:9000/mcp \ -H "Content-Type: application/json" \ -H "MCP-Session-Id: a9f9de82af6938bc..." \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' curl -X POST http://localhost:9000/mcp \ -H "Content-Type: application/json" \ -H "MCP-Session-Id: a9f9de82af6938bc..." \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_documents","arguments":{"collection":"blog"}}}' curl -X POST http://localhost:9000/mcp \ -H "Content-Type: application/json" \ -H "MCP-Session-Id: a9f9de82af6938bc..." \ -d '{"jsonrpc":"2.0","id":4,"method":"prompts/list"}'

Client Configuration

For MCP clients that support Streamable HTTP transport:

{ "mcpServers": { "mddb": { "transport": "streamable-http", "url": "http://localhost:9000/mcp" } }
}

MCP-over-SSE Transport (Legacy)

The legacy MCP-over-SSE transport (2024-11-05 spec) is still supported for backward compatibility.

How It Works

1. Client connects to GET http://localhost:9000/sse (SSE stream)
2. Server sends an endpoint event with a URL: /message?sessionId=<id>
3. Client POSTs JSON-RPC requests to http://localhost:9000/message?sessionId=<id>
4. Server sends JSON-RPC responses back via the SSE stream as message events

Client Configuration

{ "mcpServers": { "mddb": { "transport": "sse", "url": "http://localhost:9000/sse" } }
}

Endpoints

## Per-Protocol Access Modes Each protocol can have its own read/write mode, independent of the global `MDDB_MODE`: | Env Var | Protocol | Default |
|---------|----------|---------|
| `MDDB_MODE` | <strong>Global</strong> (all protocols) | `wr` |
| `MDDB_API_MODE` | HTTP/JSON REST + GraphQL | inherits `MDDB_MODE` |
| `MDDB_GRPC_MODE` | gRPC | inherits `MDDB_MODE` |
| `MDDB_MCP_MODE` | MCP (stdio + Streamable HTTP + SSE) | inherits `MDDB_MODE` |
| `MDDB_HTTP3_MODE` | HTTP/3 (QUIC) | inherits `MDDB_MODE` | Values: `read`, `write`, `wr` (read-write) <strong>Example: MCP read-only, API read-write</strong> ```bash
docker run -d \ -e MDDB_MCP_MODE=read \ -p 11023:11023 -p 9000:9000 \ tradik/mddb:latest

In read-only mode, MCP tools with readOnlyHint=false (write, delete, destructive tools) return an error. Read-only tools (search, stats, list, export) work normally.

Disabling Built-in Tools

Set MDDB_MCP_BUILTIN_TOOLS=false to hide all 54 built-in tools, exposing only custom YAML tools:

docker run -d \ -e MDDB_MCP_BUILTIN_TOOLS=false \ -e MDDB_MCP_CONFIG=/app/mcp_config.yaml \ tradik/mddb:latest

This restricts AI agents to domain-specific tools only — no direct access to add_document, delete_collection, etc.

Custom Tools in Read-Only Mode

Custom tools that use read-only actions (semantic_search, search_documents, full_text_search, fts_languages) work in read-only and follower modes. This enables public MCP endpoints on follower instances:

docker run -d \ -e MDDB_REPLICATION_ROLE=follower \ -e MDDB_REPLICATION_LEADER_ADDR=leader:11024 \ -e MDDB_MCP_BUILTIN_TOOLS=false \ -e MDDB_MCP_CONFIG=/app/mcp-tools.yml \ tradik/mddb:latest

Custom tools with write actions are blocked in read-only mode, same as built-in write tools.

API Key Authentication

Protect MCP endpoints with API keys:

docker run -d \ -e MDDB_MCP_API_KEY_ENABLED=true \ -e MDDB_MCP_API_KEYS="sk-abc123:claude-prod,sk-def456:cursor-dev" \ tradik/mddb:latest

Clients authenticate via X-API-Key header, Authorization: Bearer header, or ?api_key= query param (for SSE):

claude mcp add mydb --transport http https://mydb.example.com/mcp \ --header "X-API-Key: sk-abc123" curl -X POST https://mydb.example.com/mcp \ -H "X-API-Key: sk-abc123" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Rate Limiting

Protect against abuse with per-client rate limits:

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Returns 429 Too Many Requests with Retry-After header when exceeded.

Request Logging

Enable structured JSON audit logs for all MCP requests:

MDDB_MCP_LOGGING_ENABLED=true
MDDB_MCP_LOGGING_LEVEL=info # debug|info|warn|error

Log output (to stderr):

{"timestamp":"2026-03-26T10:30:00Z","method":"POST","path":"/mcp","status":200,"duration_ms":45,"client_ip":"1.2.3.4","key_name":"claude-prod","session_id":"abc123","user_agent":"claude-code/1.0"}

MCP Protocol Features (2025-11-25)

MDDB implements the full MCP 2025-11-25 specification:

Built-in Prompts

Claude Desktop / Claude Code

MCP is built directly into the MDDB server — no separate service needed.

Docker (Recommended)

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.jsonLinux: ~/.config/Claude/claude_desktop_config.json

{ "mcpServers": { "mddb": { "command": "docker", "args": [ "run", "-i", "--rm", "--network", "host", "-v", "mddb-data:/app/data", "-e", "MDDB_MCP_STDIO=true", "tradik/mddb:latest" ], "env": {} } }
}

Local Binary

Use the mddbd binary directly:

{ "mcpServers": { "mddb": { "command": "/path/to/mddbd", "args": [], "env": { "MDDB_MCP_STDIO": "true", "MDDB_PATH": "/path/to/mddb.db" } } }
}

Available MCP Tools (54+)

Once connected, your LLM agent has access to all built-in tools (with annotations for auto-approve):

Document Managementadd_documentupdate_documentdelete_documentsearch_documentsget_document_metaadd_documents_batchdelete_documents_batch

Searchsemantic_searchfull_text_searchhybrid_searchcross_search

Vectorvector_reindexvector_stats

Collectionsdelete_collectionget_collection_configset_collection_configlist_collection_configs

Analysisclassify_documentfind_duplicatesget_checksum

Revisionslist_revisionsrestore_revisiontruncate_revisions

Upload & Importupload_fileimport_urlingest_documents

Export & Backupexport_documentscreate_backuprestore_backup

Full-Text Search Configlist_synonymsadd_synonymdelete_synonymlist_stopwordsadd_stopwordsdelete_stopwords

Schemasset_schemaget_schemadelete_schemalist_schemasvalidate_document

Webhooksregister_webhooklist_webhooksdelete_webhook

Automationlist_automationcreate_automationget_automationupdate_automationdelete_automationtest_automationget_automation_logs

Systemget_statsset_ttlget_meta_keys

ChatGPT (Custom GPT)

Create a Custom GPT that connects to MDDB via its REST API.

1. Go to platform.openai.com/gpts
2. Create or edit a Custom GPT
3. In Configure → Actions → Create new action
4. Paste this OpenAPI schema (replace the server URL with your domain):

{ "openapi": "3.1.0", "info": { "title": "MDDB API", "version": "2.9.11" }, "servers": [{ "url": "https://your-domain:11023" }], "paths": { "/v1/search": { "post": { "operationId": "searchDocuments", "summary": "Search documents by metadata", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection": { "type": "string" }, "filterMeta": { "type": "object" }, "limit": { "type": "integer", "default": 10 } } } } } } } }, "/v1/vector-search": { "post": { "operationId": "semanticSearch", "summary": "Semantic search using vector embeddings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collection": { "type": "string" }, "query": { "type": "string" }, "topK": { "type": "integer", "default": 5 } } } } } } } } }
}

Note: Your MDDB server must be publicly accessible for ChatGPT to reach it.

Ollama (Python)

Use Ollama for local LLM inference with MDDB as the knowledge base.

pip install requests ollama
ollama pull llama3.2

import requests
import ollama MDDB_URL = "http://your-domain:11023" # replace with your MDDB address def search_mddb(query, collection="docs", top_k=5): resp = requests.post(f"{MDDB_URL}/v1/vector-search", json={ "collection": collection, "query": query, "topK": top_k, "threshold": 0.6, "includeContent": True, }) return resp.json().get("results", []) def ask(question, collection="docs"): results = search_mddb(question, collection) context = "\n\n---\n\n".join( f"## {r['key']}\n{r.get('contentMd', '')[:2000]}" for r in results ) response = ollama.chat(model="llama3.2", messages=[ {"role": "user", "content": f"Answer using this context:\n{context}\n\nQuestion: {question}"}, ]) return response["message"]["content"] print(ask("What is MDDB?"))

DeepSeek

DeepSeek supports MCP via compatible clients (Cline, Continue, etc.).

Add the same MCP config as Claude Desktop to your MCP client settings:

{ "mcpServers": { "mddb": { "command": "docker", "args": [ "run", "-i", "--rm", "--network", "host", "-v", "mddb-data:/app/data", "-e", "MDDB_MCP_STDIO=true", "tradik/mddb:latest" ] } }
}

Set DeepSeek as the LLM provider in your MCP client configuration.

Manus

Add MDDB tools to your Manus agent configuration:

name: mddb_search
description: "Search the MDDB knowledge base"
type: api
endpoint: "http://your-domain:11023/v1/vector-search"
method: POST
headers: Content-Type: "application/json"
body: collection: "docs" query: "" topK: 5 includeContent: true

Bielik.ai

Bielik is a Polish LLM that can be connected to MDDB for RAG in Polish.

pip install requests

import requests MDDB_URL = "http://your-domain:11023" # replace with your MDDB address
BIELIK_API_URL = "https://api.bielik.ai/v1"
BIELIK_API_KEY = "your-api-key" def search_mddb(query, collection="docs"): resp = requests.post(f"{MDDB_URL}/v1/vector-search", json={ "collection": collection, "query": query, "topK": 5, "threshold": 0.6, "includeContent": True, }) return resp.json().get("results", []) def ask(question, collection="docs"): results = search_mddb(question, collection) context = "\n\n".join(r.get("contentMd", "")[:2000] for r in results) resp = requests.post(f"{BIELIK_API_URL}/chat/completions", headers={ "Authorization": f"Bearer {BIELIK_API_KEY}", "Content-Type": "application/json", }, json={ "model": "Bielik-11B-v2.3-Instruct", "messages": [ {"role": "system", "content": "Odpowiadaj korzystajac z kontekstu."}, {"role": "user", "content": f"Kontekst:\n{context}\n\nPytanie: {question}"}, ], }) return resp.json()["choices"][0]["message"]["content"] print(ask("Czym jest MDDB?"))

Generic REST API Integration

Any LLM agent that supports HTTP tools can connect to MDDB. Key endpoints:

See the OpenAPI specification for complete API details.

Panel Configuration

The MDDB Panel includes an LLM Connections page (sidebar → LLM Connections) with:

• Server Domain input field — set once, all configs update automatically
• Ready-to-use configuration templates for each agent
• Dynamic server address substitution
• Copy & Download buttons
• Setup instructions per agent

← Back to README