AiContextGateway — how the context gateway works
How AiContextGateway works: GitHub context sync, tokenized context links, retrieval search API, MCP tools, multi-repo systems, self-host or Cloud Plus.
AiContextGateway — how the context gateway works
Product summary
AiContextGateway is an open-source, self-hostable context gateway: it syncs AI-readable Markdown context files from a GitHub repository and serves them to AI tools through tokenized context links, a JSON and search API, MCP surfaces, optional widgets, and an optional managed assistant. Only allowlisted, audience-scoped Markdown ever reaches a model — never source code, .env files, secrets, or other audiences' files. It does not run autonomous agents and does not call a customer's product API; tickets drafted by the assistant are human-reviewed drafts, never auto-filed.
Key concepts
| term | meaning |
|---|---|
| Context file | An allowlisted Markdown file in the customer repo, written for AI consumption and safety-gated at sync. |
| Context version | An immutable snapshot of the synced files; links serve the current version automatically. |
| Context link / token | A tokenized URL under /context/... — the token travels in the URL path and scopes both audience and abilities. |
| Audience | Who a file is for (for example vendor or end-user); a token sees only its audience's files plus audience-neutral ones. |
| Ability | What a token may do: context:read, chat:read, feedback:write, ticket:intake. |
| System | A group of same-workspace projects served behind one aggregated system token. |
| Managed assistant | Optional context-grounded chat that cites sources, refuses off-scope questions, and drafts tickets for human review. |
| MCP server | @aicontextgateway/mcp — read/validate authoring tools for coding agents, no account required. |
How common tasks work
Publish context from a repo (the core flow)
| task | where | steps | notes |
|---|---|---|---|
| Ship repo context | GitHub repo + gateway | 1. Connect a GitHub repo. 2. Connect the MCP rules endpoint to a coding assistant. 3. The assistant reads the local repo and writes the Markdown context files. 4. A developer reviews, commits, and pushes. 5. The gateway catches the push and syncs allowlisted files. 6. Current context is served over links, API, and MCP. 7. Teams use it in chat, feedback, vendor-help, or ticket workflows. | Only allowlisted Markdown syncs; a safety gate rejects secret-shaped or disallowed content. |
| Pre-flight a file | MCP check tool | 1. Run check_context_file on a candidate file before committing. | Runs the same gate as sync-time validation and stores nothing. |
Consume context: links, API, search
| task | where | steps | notes |
|---|---|---|---|
| Read as Markdown | GET /context/{token} | 1. Fetch the link; the response is the audience-scoped Markdown context. | Token responses are no-store and noindex; the token is the only secret. |
| Read as JSON | GET /api/context/{token} | 1. Fetch the API form for structured consumption. | Same token, same audience scoping. |
| Search sections | GET /api/context/{token}/search?q=... | 1. Send a query. 2. Receive the top-ranked sections with path, heading, content, and score. | Deterministic lexical retrieval — heading-based sections, typo-tolerant, diacritic-folding; default 5 results, max 20 (as of August 2026). No model runs on the gateway side. |
Author with the MCP server
| task | where | steps | notes |
|---|---|---|---|
| Install | your agent's MCP config | 1. For Claude Code: claude mcp add aicontextgateway -- npx -y @aicontextgateway/mcp. 2. Other clients use the mcpServers JSON from the package README. | Node 18+; read/validate tools need no account (as of August 2026). Self-hosters point the server at their own instance URL. |
| Use the tools | agent session | 1. list_guides and get_guide for authoring guides. 2. get_rules for audiences, verticals, and allowed paths. 3. get_templates for starter files. 4. check_context_file to validate. 5. search_context to query a live token's context. | Write operations (register a project, issue tokens, trigger sync) are deliberately absent from the MCP server. |
Ground a bot or use the managed assistant
| task | where | steps | notes |
|---|---|---|---|
| Ground your own bot | search endpoint | 1. On each user message, call the search endpoint with the message as the query. 2. Splice the top sections into your own system prompt. 3. Your model answers, citing [source: path]. | Doc changes flow through on the next sync — no bot redeploys. |
| Use the managed assistant | hosted chat page, embeds, or chat API | 1. Mint a token that allows chat. 2. Share the hosted page or embed the widget. | Small contexts are embedded whole; larger ones switch to retrieval of the most relevant sections (as of August 2026). Draft tickets require the feedback ability and stay human-reviewed. |
Aggregate multiple repos with Systems
| task | where | steps | notes |
|---|---|---|---|
| One token, many repos | system token | 1. Group same-workspace projects into a System, optionally labeling each service. 2. Mint a system token. 3. Read the aggregated Markdown, JSON, or cross-repo search under /context/system/... | System tokens are read-only (context:read) in Phase 1, and a system aggregates up to 10 member projects by default (as of August 2026). |
Run it: self-host or Cloud Plus
| task | where | steps | notes |
|---|---|---|---|
| Self-host for free | Docker Compose | 1. Follow the self-host runbook. 2. Bring your own model provider key if you want the assistant (stored encrypted per project). | The server application is AGPL-licensed; the embeddable packages are MIT. |
| Use Cloud Plus | hosted cloud | 1. Subscribe to the paid Cloud Plus plan. | The managed assistant's model is included on Cloud Plus. |
Verify in the product: assistant availability, rate limits, and token caps depend on hosting mode, plan, and whether a project uses its own provider key.
Limits & gotchas
- The token travels in the URL path, so anyone holding the link has exactly the access it grants — scope, expire, and revoke tokens from the dashboard.
- Retrieval is deterministic and lexical by default (as of August 2026); a semantic embedding layer is a deliberate opt-in later addition, not a dependency.
- System tokens carry no chat or feedback abilities in Phase 1 (as of August 2026).
- The MCP server is read/validate only — any operation that writes state requires an account and is intentionally not exposed there (as of August 2026).
- On Cloud Plus platform keys, chat usage is subject to rate limits and a monthly token cap; bring-your-own keys are metered but never capped (as of August 2026).
- Assistant tickets are always drafts for human review; nothing is auto-filed to any external system.
FAQ
Does AiContextGateway send my source code to a model?
No. Models only ever see the allowlisted, audience-scoped Markdown context files that survived the safety gate. Source code, .env files, credentials, logs, and other audiences' files are never part of any prompt.
Do I need an account to use the MCP server?
No. Every tool in @aicontextgateway/mcp is read/validate only and works without an account (as of August 2026). The line is drawn at writes: anything that creates state on the gateway requires an account and lives outside the MCP server.
Whose model answers the managed assistant chat?
On self-host, your own provider key, stored encrypted per project. On the paid Cloud Plus plan, the model is included. Either way the assistant is grounded in the token's context, cites its sources, and only drafts tickets for human review.
Can one token read several repositories?
Yes — group the projects into a System and mint a system token. It serves aggregated Markdown, JSON, and cross-repo search over every member repo's approved context, read-only in Phase 1 (as of August 2026).