Arkon: a self-hosted MCP knowledge server that compiles docs into a reviewable wiki

The problem Arkon targets: fragmented paste-into-chatbot context

The README states the failure mode plainly: employees copy documents into chatbots, producing inconsistent context, security risks, and duplicated work. That is a real pattern, and it is not a retrieval problem. A vector store answers a query; it does not decide who was allowed to ask, and it does not keep the answer consistent between two people in the same department. Arkon's answer is to treat knowledge as a managed organizational resource with department and global scopes, and to expose it through one permission-scoped MCP endpoint rather than through a search box. The intended user is not an individual developer. It is an organization with HR, Legal, and Engineering documents, an existing Claude Desktop or Claude.ai deployment, and someone willing to run seven containers. The README also names a second audience: teams that want to distribute agent skill packages (.zip with SKILL.md) to departments with versioned visibility, which is a different job from knowledge retrieval and is bundled into the same product.

The MRP pipeline is the part that differs from a vector database

The README is explicit that Arkon is not chunk-and-index. Its ingestion path is Map, Reduce, Plan-review, Refine, Verify, Commit. The step worth attention is plan review: every ingestion produces a human-reviewable plan listing which wiki pages will be created or updated, and an editor can regenerate that plan with feedback before any page is written. When a new source touches an existing page, content is LLM-merged rather than overwritten, and each page records the source documents it was compiled from. Vision captions are baked into source text before compilation, so image references land in the right places. Drafts persist mid-pipeline, so a crashed run resumes without redoing the expensive LLM work. That design has a cost the README does not hide: it notes that RAM is the primary bottleneck because MRP workers load large LLM context windows into memory. The recommended floor is 4 GB for 1 to 20 people, 8 GB for 20 to 100, and 16 GB or more beyond that. A plain vector database would run in a fraction of that. The trade is a compiled wiki with traceable claims against a pile of chunks with no provenance.

Seven containers, and what each one is doing

Arkon runs PostgreSQL with pgvector, Redis, MinIO, a FastAPI API, two ARQ workers, and a Next.js frontend. The backend image is built once and reused by the API and both workers, per the x-backend anchor in docker-compose.yml. Redis carries the arq job queue for ingestion; MinIO holds files; pgvector holds embeddings for semantic search alongside full-text search. The Dockerfile ends with uvicorn on app.main:app at port 5055. The compose file maps MinIO to 9002 and 9003 on the host, and leaves PostgreSQL and Redis ports commented out, so the database and queue are not published by default. That is the right default for a knowledge store holding internal policy documents, and it means you should not expect to point a local psql at it without editing the file. The README recommends a reverse proxy (Nginx or Caddy) with SSL in front. No GPU is required because all inference happens against external Anthropic, Google, or OpenAI APIs.

Installing Arkon with Docker and connecting Claude

The repository ships .env.docker.example and .env.local.example, and docker-compose.yml reads .env.docker through env_file. Copy the example before the first start, because the compose file references POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, REDIS_PASSWORD, MINIO_ACCESS_KEY, and MINIO_SECRET_KEY, with defaults such as arkon_secret and minioadmin123 that you should not leave in place on a host reachable by others.

cp .env.docker.example .env.docker
docker compose up -d --build

The stack brings up seven containers. The healthchecks in the compose file gate the backend on Postgres, Redis, and MinIO reporting healthy, so a first run can sit for a while before the API starts.

On the client side, the README says employees connect Claude Desktop or Claude.ai through OAuth 2.1 with PKCE: add the server URL and sign in through the browser, with no manual token copying. After that, the MCP server exposes wiki tools named search_wiki, read_wiki_page, list_wiki_pages, and read_wiki_index, plus source drill-down tools get_source, get_source_outline, get_source_pages, and list_sources. A first useful check is to call search_wiki and confirm that the results are limited to the scopes attached to your token. If a query from a Legal account returns Engineering pages, the scope enforcement described in the README is not behaving as documented, and that is worth investigating before loading more documents.

Limits, failure modes, and where Arkon is the wrong tool

The plan-review step is a gate, not an optional nicety. Someone has to review and approve ingestion plans, and the README's own workflow assumes an editor role exists and is staffed. A small team that wants documents ingested and searchable within the hour will find the human step in the middle of the pipeline an obstacle rather than a feature. Second, the memory profile is genuinely high for what is, at the storage layer, a Postgres database with pgvector. The README attributes this to MRP workers loading large context windows, and it recommends 16 GB or more for organizations past 100 people. Third, the AI provider is external by design. Self-hosting keeps documents on your infrastructure, but the README states outbound traffic goes to the AI provider you choose, so the LLM and embedding vendors still see document content during compilation and embedding. If your constraint is that no third party may process the text, Arkon does not solve that; it moves the boundary rather than removing it. Fourth, the licensing is not open source in the usual sense. The README badge and LICENSE file point to PolyForm Internal Use 1.0.0, and the repository's licence field is reported as NOASSERTION. Read the actual licence text before assuming you can redistribute or offer this as a service.

Arkon versus a plain RAG pipeline on pgvector

The obvious alternative is building the same thing on Postgres with pgvector and a small ingestion script, or adopting an existing retrieval framework. The difference is where the work sits. A pgvector pipeline stores chunks and returns them ranked by similarity; access control, provenance, and consistency between users are things you add yourself, and most teams add them late. Arkon puts scopes and role-based access control in front of retrieval, with built-in roles Viewer, Contributor, Editor, and Admin, granular permissions such as doc:read:own_dept and wiki:edit:all, and an audit log for privileged actions including settings changes, plan approvals, and role updates. It also compiles pages instead of storing chunks, so two people asking the same question get the same compiled answer rather than two different sets of retrieved fragments. The cost is the operational surface: seven containers, an ARQ worker queue, MinIO, and a review workflow. If you only need semantic search over a document set and everyone is trusted equally, the plain pipeline is smaller and you will understand every part of it. If the access boundary is the actual requirement, Arkon has already built it.

Maintenance, upgrades, and licence implications

The last push to the repository was on 2026-06-03, and the most recent release is v0.9.1 from 2026-06-01, described as a fix for a minor bug in v0.9.0. The project is not archived. That is roughly three and a half months of quiet as of this writing, which is neither abandoned nor a fast-moving codebase; treat the release cadence as occasional. Upgrade mechanics are partly visible: Alembic is present with alembic.ini and an alembic/ directory, and entrypoint.sh runs before the API command, so schema migrations are part of the container start path rather than a step you run by hand. The README describes one migration that is handled carefully: switching embedding models triggers an online re-embed, and the active model is flipped atomically on completion, so there is no window where search returns zero results. That is a meaningful detail for anyone planning a provider switch, and it is the kind of thing most projects leave undocumented. On licensing, PolyForm Internal Use 1.0.0 is not an OSI open source licence; it typically permits internal business use while restricting redistribution and competing services. The README does not spell out those terms, so read LICENSE directly and get your own advice if the deployment is customer-facing.

Editorial conclusion

Adopt Arkon if your organization already has Claude or another MCP client in daily use and the real problem is that each employee pastes different documents into it. Skip it if you want a lightweight RAG endpoint; seven containers and a human plan-review step are not a fit for that. Before deploying, read LICENSE and confirm what PolyForm Internal Use 1.0.0 permits for your organization, then check that docker-compose.yml's MinIO port mapping (9002:9000, 9003:9001) does not collide with anything already bound on the host.

Frequently asked questions

Official sources

1. Issues
2. nduckmink/arkon on GitHub
3. README
4. Releases