When integrating artificial intelligence into software systems, the default approach has often been crude: expose raw REST endpoints, dump unparsed database rows into prompt contexts, or expect LLMs to behave like human web browsers. None of these patterns scale to production.
In early 2026, we adopted the Model Context Protocol (MCP) to connect AI assistants directly to Wikantik. However, exposing all operations through a single MCP server surfaced a practical trade-off: read-only retrieval agents and administrative maintenance agents have very different tool and security requirements.
An agent acting as an interactive coding assistant needs fast, low-token, read-only grounded retrieval. Conversely, a content-auditing agent needs privileged tools to repair broken links, update documentation, and manage clusters with strict concurrency controls.
Putting all tools into a single MCP endpoint degraded agent performance: the massive combined tool schema consumed thousands of context tokens on every request, while elevating the security risk of accidental writes during read-only research. Wikantik solved this by engineering a Dual-MCP Architecture.
The Dual-Gateway Architecture
Wikantik partitions its agent-facing surface into two specialized, independently authenticated protocol endpoints:
1. /knowledge-mcp: The RAG-First Consumption Gateway
Designed for low overhead, grounded context retrieval, and zero destructive capabilities:
retrieve_context: The primary workhorse for AI agents. Rather than dumping entire articles, this tool queries the hybrid Lucene+pgvector engine, executing Reciprocal Rank Fusion and returning structured pages containing only their contributing chunks alongside relevance scores and related-page co-mention hints.get_page_for_agent: A token-budgeted page projection. If an agent has a 1,500-token budget for an article, the tool dynamically strips unnecessary frontmatter, compresses repetitive tables, and projects the document to fit the specified token envelope without truncation artifacts.list_clusters&list_pages_by_filter: Structural exploration tools that allow agents to discover topical hubs and filter articles by cluster membership, status, or tags without loading full document bodies.list_stale_citations: Inspects the inline citation graph to identify articles citing upstream documents that have changed since the citation was recorded.
2. /wikantik-admin-mcp: The Verified Management Gateway
Designed for autonomous curators, batch maintenance bots, and human administrators:
- Optimistic Concurrency Control: Editing wiki content requires passing an explicit version check (
expected_version). If another user or agent updated the page in the interim, the write fails with a conflict error rather than silently clobbering edits. - Cluster Management (
rename_cluster): A plan-first, atomic batch operation. Renaming a cluster inspects every member document, rewrites the frontmattercluster:tag across dozens of files, and commits the changes within a single transactional boundary. - Link & Health Triage: Tools like
find_broken_linksandfind_orphan_pagesallow maintenance agents to automatically audit documentation health and submit targeted pull-request-style updates. - Knowledge Graph Curation: Approving, editing, or revoking extracted semantic entity triples and SHACL constraints.
A common defect in multi-protocol architectures is logic duplication: search implemented in a REST controller behaves differently than search in an MCP tool or CLI. In April 2026, Wikantik unified its retrieval stack under a single ContextRetrievalService interface inside the wikantik-knowledge module. The React UI, the REST API, the OpenWebUI tool bridge, and the /knowledge-mcp server all route through this single shared service, guaranteeing identical hybrid retrieval behavior across every client.
Supporting Non-MCP Clients: The OpenAPI Tool Bridge
While Model Context Protocol is the preferred standard for modern coding assistants like Claude Desktop, Cursor, and Antigravity, older or specialized LLM orchestrators (such as OpenWebUI or custom LangChain/LlamaIndex agents) frequently rely on standard OpenAPI specifications.
To maintain interoperability without fragmenting the backend, Wikantik ships an OpenAPI 3.1 Tool Server mounted alongside the MCP gateways. This tool server exposes identical function schemas and parameter constraints, delegating directly to ContextRetrievalService and enforcing the same RBAC authorization rules.
The Impact of Specialized Tool Surfaces
Splitting the agent interface into two gateways produced three operational benefits:
- Token Efficiency: Agents interacting with
/knowledge-mcpload only the compact tool schemas necessary for retrieval, saving over 40% of prompt preamble overhead compared to monolithic tool definitions. - Security Guarantees: An agent performing exploratory research or answering user queries can be issued a token scoped strictly to
/knowledge-mcp, preventing accidental page edits or deletions at the protocol layer. - Predictable Task Scoping: Autonomous maintenance agents run against
/wikantik-admin-mcpin focused, batch-driven loops with explicit audit logs and optimistic locking.
With robust protocols connecting agents to the wiki, the final phase of Wikantik's evolution brought all these strands together into a modern production system: RAG-as-a-Service, automated document ingest, and grounded context delivery. To wire Claude Code, Gemini CLI, or an OpenAPI client into the live endpoints today, follow the MCP Integration guide on the wiki.
Comments