ACG MCP Server

Standalone MCP server for the Audited Context Generation (ACG) Protocol — verifiable fact-checking and grounded RAG via MongoDB.

ACG provides a dual-layer standard for veracity assurance:

• UGVP (Layer 1): Atomic fact grounding with Claim Markers and Source Hash Identity (SHI)
• RSVP (Layer 2): Logical synthesis verification with Relationship Markers

Why ACG — what you can do with it

LLMs confidently state things that are wrong, and there is usually **no way to

check** — the answer is a black box with no provenance. ACG fixes this by making

every answer auditable by construction:

• Ground every fact to its source. Index a URL once and every later answer

built from it carries inline Claim Markers like

`[C1:9f7a2c4d8e1b:css=#acg-chunk-aa-0]` — the SHA-256-based SHI prefix

fingerprints the exact source document, and the CSS selector points to the

precise chunk inside it.

• Verify instead of trust. `acg_verify_claims` re-fetches every source and

fuzzy-matches each claim against the actual text, so verification is not a

self-reported LLM opinion — it is an independent, repeatable check. A claim

either exists in the cited source or it fails.

• Know when the knowledge base is enough. `acg_check_indexed` returns a

confidence score (HIGH / MEDIUM / LOW) before you ever hit the network, so

you only fetch new pages when the index genuinely can't answer.

• Get a machine-readable audit trail. `acg_build_var` emits a Veracity

Audit Registry (SSR + RAR entries) — a JSON record of every claim, its

source fingerprint, and every logical relationship between claims, ready to

be consumed by downstream systems or humans.

• Use it in two modes. Run the enforced workflow (`acg_run_workflow`)

and get a complete, verified, audited answer in one call — or compose the

individual tools any way your own workflow requires (see

Two ways to use ACG).

In short: ACG turns "trust me, the model said so" into

**"here is the claim, here is the exact source location, here is the

verification result, and here is the audit record."**

Features

• Enforced workflow → One call runs the whole pipeline: search, auto-index,

ground, verify, audit (see Two ways to use ACG)

• Index URLs → Extract text, chunk by sentences, generate embeddings, store in MongoDB
• Search Sources → Semantic (vector) + keyword search across indexed content
• Check Indexed → Confidence-scored lookup to avoid unnecessary web_fetch calls
• Generate Grounded Text → Create verifiable output with inline Claim Markers
• Verify Claims → Re-fetch sources, fuzzy-match claims against source text
• Build VAR → Generate machine-readable Veracity Audit Registry (SSR + RAR)
• Crawl & Index → BFS URL discovery + automatic ACG indexing pipeline
• Reset Database → Drop all ACG collections (with confirmation guard)

Requirements

• Python 3.11+
• MongoDB instance (local or Atlas)
  • Atlas Vector Search is optional — falls back to keyword search if no embedding model

Installation

Requires Python 3.11+. A virtual environment is strongly recommended —

on recent Debian/Ubuntu (23.04+) and other PEP 668 distros, bare `pip install`

refuses to write to the system Python, so Option A is the reliable path there.

Option A: Virtual environment + editable install (recommended)

git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -e .

This installs the package and its dependencies into the venv and puts the

`acg-mcp` command on PATH while the venv is active. Editable mode means

local code changes apply immediately — no reinstall needed.

MCP clients don't source your shell, so point them at the venv's binary

by absolute path instead of relying on PATH (see Connect from an MCP client).

Option B: System-wide install (agents / CLI tools)

If you want `acg-mcp` available on PATH from any directory without a venv:

git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp
pip install -e .

If pip fails with `externally-managed-environment` (PEP 668), either use a venv

(Option A) or add `--break-system-packages`.

Option C: Run from source (no install)

git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp
pip install -r requirements.txt
# Must be run from the project root:
python -m src.server

Configuration

Copy `.env.sample` to `.env` and configure:

# MongoDB connection string (required)
MONGO_URI=mongodb://localhost:27017

# MongoDB database name (optional, default: acg_protocol)
MONGO_DB=acg_protocol

# Embedding model cache directory (optional)
EMBEDDING_CACHE_DIR=

# Vector search candidate cap (optional, default: 10000).
# Number of embedded chunks scanned per query. Raise it if your index
# exceeds this and you see false "LOW confidence" results.
ACG_VECTOR_MAX_CANDIDATES=10000

For MongoDB Atlas:

MONGO_URI=mongodb+srv://:@.mongodb.net/acg_protocol?retryWrites=true&w=majority

Usage

Run the MCP server (stdio transport)

After installing with Option A or B:

# venv (Option A): works while the venv is active
# system-wide (Option B): works from any directory
acg-mcp

Without installing the CLI (source directory only):

cd /path/to/acg_mcp
python -m src.server

Run the enforced workflow from the CLI

The one-shot CLI runs the entire audited pipeline without an MCP client:

# Query the index, print the grounded answer + audit footer
acg-mcp --workflow "What does the README say about MONGO_URI?"

# Same, but auto-index a URL first when confidence is LOW
acg-mcp --workflow "How do I configure MongoDB Atlas?" https://example.com/docs/setup

Connect from an MCP client

The server communicates over stdio. Claude Desktop and Opencode use

different config formats, so the examples below are split per client:

Claude Desktop uses the `mcpServers` key; Opencode uses a top-level `mcp`

key where every server needs `"type"` and `command` is an array.

Claude Desktop

Claude Desktop reads `claude_desktop_config.json` and uses the `mcpServers`

key. If you installed with Option A (venv), point at the venv binary —

clients don't source your shell:

{
  "mcpServers": {
    "acg-mcp": {
      "command": "/absolute/path/to/acg_mcp/venv/bin/acg-mcp",
      "env": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

With a system-wide install (Option B), the bare command works directly:

{
  "mcpServers": {
    "acg-mcp": {
      "command": "acg-mcp",
      "env": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Opencode

Opencode reads `opencode.json` (or `opencode.jsonc`) and uses a top-level

`mcp` key. Local servers require `"type": "local"`, `command` as an array

of the binary + args, and env vars under `"environment"` (not `"env"`):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["/absolute/path/to/acg_mcp/venv/bin/acg-mcp"],
      "enabled": true,
      "environment": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

With a system-wide install (Option B), use the bare command:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["acg-mcp"],
      "enabled": true,
      "environment": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Running from source directory

If you haven't installed the CLI, use the full path. Claude Desktop:

{
  "mcpServers": {
    "acg-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Opencode — note `cwd` so `src.server` resolves relative to the project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["python", "-m", "src.server"],
      "cwd": "/path/to/acg_mcp",
      "environment": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

> Important: When using `python -m src.server`, run the MCP client from

> the project root (`/path/to/acg_mcp`) or set `cwd` in the MCP config.

Config locations

Two ways to use ACG

ACG ships both an enforced end-to-end workflow and the individual tools

it is built from. Use whichever fits your task.

1. Enforced workflow — the whole protocol in one call

Call `acg_run_workflow(query, url="")` and the server runs the full

pipeline for you, in this order:

1. search — search the indexed sources for the query

2. index — if confidence is LOW and a `url` was provided, index it

first, then re-search (auto-fetch)

3. ground — compose a grounded answer with inline UGVP Claim Markers

4. verify — re-fetch every cited source and fuzzy-match each claim

5. audit — build the Veracity Audit Registry (SSR + RAR)

The single returned report contains everything: the grounded answer,

per-claim verification results, a Chunk Signatures Table, and the

audit footer — `[Claims Verified: x/y]`, `[ACG Accuracy: N%]`,

`[ACG Signed: ACG Protocol]`. You get a verifiable answer without

orchestrating any of the steps yourself.

// acg_run_workflow("What is the pricing of the flash model?")
{
  "query": "What is the pricing of the flash model?",
  "workflow": ["search", "ground", "verify", "audit"],
  "confidence_tier": "HIGH",
  "grounded_answer": "Flash input tokens cost $0.14 per 1M [C1:9f7a2c4d8e1b:css=#acg-chunk-aa-0].",
  "claims_verified": "1/1",
  "acg_accuracy": 100.0,
  "acg_signed": "ACG Protocol",
  "var": { "protocol": "ACG/1.0", "ssr_entries": [ /* ... */ ], "rar_entries": [] }
}

2. Individual tools — adapt ACG to your own workflow

Every step is also available as a standalone tool, so you can compose

exactly the pipeline your workflow needs — different chunking, custom

verification thresholds, your own retrieval strategy, or ACG used purely

as a post-generation audit layer.

For example, a "verify-only" workflow that audits text generated elsewhere:

acg_generate_grounded_text(claim, shi_prefix, css_selector)
    -> acg_verify_claims(grounded_text)
    -> acg_build_var(grounded_text)

Usage from other tools & agents

Once installed with Option A (venv) or Option B (system-wide), any tool or

agent on the machine can use acg-mcp by referencing it in their MCP configuration.

Add it to the agent's global Opencode config

(`~/.config/opencode/opencode.json`) using Opencode's `mcp` syntax:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["acg-mcp"],
      "enabled": true,
      "environment": {
        "MONGO_URI": "mongodb://localhost:27017"
      }
    }
  }
}

The agent can then call ACG tools directly:

• `acg_run_workflow()` — One call: full verified, audited answer
• `acg_check_indexed()` — Check if answers exist in indexed sources
• `acg_index_url()` — Index new URLs
• `acg_verify_claims()` — Verify grounded text claims
• `acg_search_sources()` — Search indexed knowledge base

Passing environment variables

Pass `MONGO_URI` and other config via the `env` field (Claude Desktop) or

`environment` field (Opencode) in the MCP config. The server also loads

`.env` from the project directory (via python-dotenv) when installed

editable (`pip install -e .`) or run from the project root.

Available Tools

Database Collections

The server uses a standard MongoDB collection structure:

Indexes are auto-created on first connection.

License

MIT