MCP Server Configuration

MDDB has a built-in MCP (Model Context Protocol) server implementing the 2025-11-25 specification. This document covers all MCP configuration options.

→ LLM client setup (Claude, Cursor, ChatGPT, Ollama) | → Custom YAML tools

Transports

All transports run on the MCP port (default: 9000, configurable via MDDB_MCP_ADDR).

Streamable HTTP (Recommended)

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

Client Configuration

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

Environment Variables

Core

Server Info

Tools

API Key Authentication

Two sources of keys:

• Static — MDDB_MCP_API_KEYS env var (defined at startup, no restart needed to validate)
• Dynamic — REST API (/v1/mcp/keys) stored in BoltDB, persists across restarts, managed without downtime

Clients authenticate via:

• X-API-Key: <key> header
• Authorization: Bearer <key> header
• ?api_key=<key> query parameter (for SSE connections)

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

Dynamic Key Management API

Keys stored in internal BoltDB bucket (_mcp_api_keys). Requires admin auth when MDDB_AUTH_ENABLED=true.

curl -X POST http://localhost:11023/v1/mcp/keys \ -H "Authorization: Bearer <admin-token>" \ -d '{"name": "claude-prod", "expiresAt": 0}' curl http://localhost:11023/v1/mcp/keys \ -H "Authorization: Bearer <admin-token>" curl -X DELETE http://localhost:11023/v1/mcp/keys \ -H "Authorization: Bearer <admin-token>" \ -d '{"key": "mcp_a1b2c3d4e5f6..."}' curl -X POST http://localhost:11023/v1/mcp/keys/disable \ -H "Authorization: Bearer <admin-token>" \ -d '{"key": "mcp_a1b2c3d4e5f6..."}'

Key features:

• TTL support — expiresAt Unix timestamp (0 = never expires)
• Disable without delete — revoke instantly, keep for audit
• Cache — lookups cached for MDDB_MCP_API_KEY_CACHE_TTL (default 60s), auto-invalidated on create/delete/disable
• Panel UI — manage keys from the web panel (LLM Connections → API Keys tab)

Rate Limiting

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

Request Logging

Logs are written to stderr in JSON format:

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

Access Modes

Each protocol can have its own read/write mode:

In read-only mode:

• Built-in tools with readOnlyHint=true (search, stats, list, export) → allowed
• Built-in tools with writes/deletes → blocked with error
• Custom tools with read-only actions (semantic_search, search_documents, full_text_search) → allowed
• Custom tools with write actions → blocked

docker run -d \ -e MDDB_MCP_MODE=read \ -e MDDB_MCP_BUILTIN_TOOLS=false \ -e MDDB_MCP_API_KEY_ENABLED=true \ -e "MDDB_MCP_API_KEYS=sk-public:external" \ -e MDDB_MCP_RATE_LIMIT_ENABLED=true \ -e MDDB_MCP_RATE_LIMIT_REQUESTS=60 \ -e MDDB_MCP_LOGGING_ENABLED=true \ -e MDDB_MCP_CONFIG=/app/tools.yml \ tradik/mddb:latest

Protocol Features (2025-11-25)

Memory RAG Tools

Built-in MCP tools for conversational memory and RAG:

Example: Agent with Memory

// 1. Start session
{"name": "memory_start_session", "arguments": {"user_id": "user-1", "scenario": "support"}} // 2. Store messages as conversation progresses
{"name": "memory_add_message", "arguments": {"session_id": "abc...", "role": "user", "content": "How do I use vector search?"}}
{"name": "memory_add_message", "arguments": {"session_id": "abc...", "role": "assistant", "content": "Use POST /v1/vector-search..."}} // 3. In a future session, recall relevant context
{"name": "memory_recall", "arguments": {"query": "vector search usage", "user_id": "user-1", "top_k": 5, "include_content": true}} // 4. Summarize when done
{"name": "memory_summarize", "arguments": {"session_id": "abc..."}}

Built-in Prompts

← Back to README | → LLM Connections | → Custom Tools