MCP Integration

What MCP is (short) + what Conduit provides

MCP is a standard interface that lets AI tools call local or remote tools in a predictable way. Conduit uses MCP to act as a private context service: your client asks for specific information, and Conduit returns just enough context with citations.

Conduit is not an LLM. It is the retrieval and context engine that sits between your KB and your AI client.

Image

conduit-mcp-architecture | alt: Diagram showing AI clients connecting to Conduit MCP server on the local machine, which queries the local KB (RAG vectors) and optional KAG graph store, returning only the requested snippets/citations.

What Conduit exposes over MCP

Conduit exposes a read-only Knowledge Base surface with these MCP tools:

kb_search: Hybrid, semantic, or keyword search with snippets and scores.
kb_search_with_context: Returns merged, prompt-ready context with citations.
kb_list_sources: Lists KB sources with IDs and stats.
kb_get_document: Retrieves a full document by ID.
kb_stats: KB statistics and capability summary.
kag_query: Optional knowledge graph query (only when KAG is enabled and synced).

Security posture and guardrails:

Conduit only accesses sources you explicitly added via conduit kb add.
MCP is read-only: it does not expose kb add, kb remove, or kb sync.
Results return minimal chunks plus citations to avoid oversharing.
Paths outside indexed sources are not exposed.

For deeper protocol and tool details, see /docs/architecture and the upstream MCP design doc: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/MCP_SERVER_DESIGN.md

Prerequisites

Keep the setup short and verified:

Install Conduit and dependencies: /docs/install
Ensure the daemon is healthy: conduit status
Add sources and sync at least once: conduit kb add, conduit kb sync
Optional: semantic search requires Qdrant + Ollama; KAG requires conduit kb kag-sync

If anything looks off, run conduit mcp status and /docs/troubleshooting.

Generate / locate the MCP server configuration

Conduit can generate or validate MCP config for supported clients:

# Show MCP readiness and capabilities
conduit mcp status
 
# Auto-configure supported clients (default: Claude Code)
conduit mcp configure
 
# Target a specific client
conduit mcp configure --client cursor
conduit mcp configure --client vscode
 
# See detected clients and config paths
conduit client list

If you need to configure manually, the MCP server entry looks like this:

{
  "mcpServers": {
    "conduit-kb": {
      "command": "conduit",
      "args": ["mcp", "kb"]
    }
  }
}

If you use a non-default Conduit home, add an environment override:

"env": {
  "CONDUIT_HOME": "/Users/you/.conduit"
}

Note on secrets: If you enable KAG with a hosted provider, prefer environment variables like OPENAI_API_KEY or ANTHROPIC_API_KEY rather than hardcoding secrets into client config.

Add Conduit to your AI client

Image

mcp-client-config-flow | alt: Flowchart: Generate MCP config -> add to client config -> restart client -> test tool call -> verify response.

Claude Code

Auto-registered by the install script in most setups.
Config file: ~/.claude.json
You can re-run: conduit mcp configure
Manual snippet (if needed):

{
  "mcpServers": {
    "conduit-kb": {
      "command": "conduit",
      "args": ["mcp", "kb"],
      "env": {
        "CONDUIT_HOME": "/Users/yourname/.conduit"
      }
    }
  }
}

Restart Claude Code and run /mcp to confirm conduit-kb is listed.

Claude Desktop

Config file (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
Add the standard mcpServers entry shown above.
Restart the app. Success looks like Conduit tools appearing in the MCP tool list.

Cursor

Config file paths in the docs:
- ~/.cursor/mcp.json (User Guide)
- .cursor/settings/extensions.json (MCP design doc)
Use conduit client list to confirm the path on your machine.
Add the standard mcpServers entry and restart Cursor.
You can also run: conduit mcp configure --client cursor

VS Code

Config file paths in the docs:
- ~/.vscode/mcp.json (User Guide)
- .vscode/settings.json with mcp.servers (MCP design doc)
If using .vscode/settings.json, use this shape:

{
  "mcp.servers": {
    "conduit-kb": {
      "command": "conduit",
      "args": ["mcp", "kb"]
    }
  }
}

Restart VS Code or reload the window. You can also run: conduit mcp configure --client vscode.

If your client is not listed here, it is not documented in the MCP guide yet. Use conduit client list and the upstream CLI index to confirm supported paths.

Test it (2-3 quick validations)

Use small prompts that should yield predictable tool output:

"Search my KB for authentication and cite sources."
"Search my KB for not-a-real-term-123 and tell me if there are no results."
If KAG is enabled: "Using the knowledge graph, show relationships for Kubernetes."

Expected behavior: Conduit returns snippets and citations via MCP; your AI client writes the final answer.

Troubleshooting

Symptom	Likely cause	Fix
MCP server not showing up in the client	Wrong config path or client not restarted	Run `conduit client list`, fix the path, restart the client, then run `conduit mcp status`.
Tool calls time out	Daemon not running or dependencies are down	Check `conduit status`, `conduit mcp logs`, `conduit qdrant status`, `conduit ollama status`.
Searches return no results	Sources not synced or stale index	Run `conduit kb sync` (or `conduit kb sync --rebuild-vectors` if needed).
Permission/path issues	Source not added or path outside KB	Run `conduit kb list`, add the source, then sync.
KAG queries are very slow	First run or model cold start	Run `conduit kb kag-status`, `conduit kb kag-sync`, and optionally `conduit ollama warmup`.

For more, see /docs/troubleshooting and the upstream Known Issues doc: https://github.com/amlandas/Conduit-AI-Intelligence-Hub/blob/main/docs/KNOWN_ISSUES.md

Design notes (short, PM-grade)

Conduit treats MCP as a read-only, least-privilege surface. It is an answer engine, not a dump truck: the goal is minimal context with citations, not wholesale data transfer. This keeps responses grounded and protects your local data. MCP provides a stable interface so multiple clients can share the same KB without bespoke integrations. The tool surface is intentionally small to limit risk and keep behavior predictable. Semantic search and KAG are optional enhancements that only activate when their dependencies are available. For now, Conduit focuses on a single, reliable KB MCP server. Longer term, Conduit may expand into managed MCP hubs for third-party servers, but that is not shipped today.