aaaa-nexus-mcp 0.1.1

Claude Code MCP plugin for the AAAA-Nexus trust, security, and agent infrastructure API

AAAA-Nexus

Developer infrastructure for trustworthy agents. 140 MCP tools across 19 categories for trust, security, compliance, RAG, payments, and agent orchestration.

pip install aaaa-nexus-mcp           # Python + Claude / Cursor / Codex MCP
npm install @atomadic/nexus-client   # TypeScript / Node / Deno / Bun
curl https://atomadic.tech/health    # or skip the SDK entirely

No key needed for the free tier. Grab one at atomadic.tech/pay when you want the paid surface.

---

Why agents call AAAA-Nexus directly

Your agent is already writing code, making decisions, and spending tokens. What it cannot do on its own:

1. Prove its outputs aren't hallucinated.
2. Detect drift before it compounds.
3. Share a LoRA adapter with the rest of the swarm.
4. Earn rewards when its fixes train the next model.
5. Pull trusted RAG context with provenance receipts.
6. Gate its own commits on a tamper-evident lint + trust score.
7. Escrow a payment on outcome-based delivery.
8. Certify its trace for EU AI Act Annex IV, GDPR Art. 22, and NIST AI-RMF.

AAAA-Nexus does all of that. At the HTTP layer. In one call.

---

The two flywheels that matter

1. Shared LoRA — earn while you code

Every (buggy_code → fix) pair your agent produces is a training sample. Contribute it to the shared pool and you get back:

• Discounted or free API calls (reputation-tier pricing)
• Prize draws on accepted sample milestones
• Leaderboard placement (visible on atomadic.tech)
• Access to the community-trained adapter for your language

The loop is four calls:

from aaaa_nexus_mcp.client import NexusAPIClient

async with NexusAPIClient(api_key="an_...") as c:
    # 1. Capture locally (free, PII-scrubbed, hash-chained)
    await c.post("/v1/lora/capture", {"bad": bad, "good": good, "language": "python"})

    # 2. Contribute the buffered batch (micro-rebate per accepted sample)
    await c.post("/v1/lora/contribute", {"min_quality": 0.6})

    # 3. Pull the current community adapter
    adapter = await c.get("/v1/lora/adapter/python")

    # 4. Claim your reputation reward
    await c.post("/v1/lora/reward/claim", {"agent_id": "my-agent-001"})

See examples/lora_flywheel.py for the end-to-end script.

2. Trusted RAG cycle — provenance or it didn't happen

Ordinary RAG pulls whatever the vector index returns. Trusted RAG gates each chunk on:

• Source domain allowlist
• Freshness window
• Hallucination oracle verdict on the retrieved text
• Drift score against the live knowledge graph
• Tamper-evident receipt (SHA-256 chained to the lineage vault)

ctx = await c.post("/v1/rag/augment", {
    "query": "latest EU AI Act Annex IV requirements",
    "max_results": 5,
    "freshness_hours": 168,
    "source_policy": "trusted_only",
    "required_domains": ["europa.eu", "nist.gov"],
})
# ctx["results"][i] includes: text, source_url, trust_score, receipt_hash

Every response ships with a _guard block: {hallucination, drift, guarded_at}. You never have to run those checks yourself.

See examples/trusted_rag.py for the full cycle including certificate emission.

---

Key capabilities

#	Capability	Representative endpoints	What it solves
1	Trust oracles	/v1/oracle/hallucination, /v1/trust/decay	Hallucination + drift verdicts on any text
2	Shared LoRA loop	/v1/lora/contribute, /v1/lora/reward/claim	Earn rewards contributing fixes; pull the community adapter
3	Trusted RAG	/v1/rag/augment, /v1/aibom/drift	Provenance-gated retrieval with receipts
4	Sys primitives	/v1/sys/trust_gate, /v1/sys/lint_gate, /v1/sys/chain_parity	Numerical invariants for agent self-governance
5	Compliance certs	/v1/compliance/eu-ai-act, /v1/compliance/explain	EU AI Act, GDPR Art. 22, NIST conformance
6	Escrow + SLA	/v1/escrow/create, /v1/sla/report	Outcome-based USDC billing with arbitration
7	VeriRand	/v1/rng/quantum, /v1/vrf/draw	HMAC-proven randomness, on-chain VRF draws

Total: 140 tools across 19 categories. The exact per-category breakdown lives in docs/TOOLS.md, which is the repo’s public source of truth for the current catalog.

---

Infrastructure that agents call directly

One base URL. Bearer auth. JSON in / JSON out. Every response is already guarded.

POST https://atomadic.tech/v1/<category>/<verb>
Authorization: Bearer an_your_key
Content-Type: application/json

The MCP plugin, the Python SDK, the npm package, and your own curl calls all hit the same surface. No SDK lock-in, no proprietary wire format, no required ceremony beyond a Bearer header.

---

Enhancement Architect Prompt Patterns

AAAA-Nexus documents three operating patterns you can use to turn any LLM into a self-improving agent wired to the trust + LoRA + RAG stack:

• DADA — Delegator Atomadic Developer Agent (routes tasks, verifies in a separate lane)
• Atomadic — Intent interpreter & prompt refiner
• Autopoetic — Self-healing feedback loop

Use them as starting points in your CLAUDE.md, .cursorrules, or system prompt field when you want the agent to use nexus_* tools intentionally.

---

Quickstarts — pick your lane

1. Claude Code / Cursor / VS Code (MCP)

Install once:

pip install aaaa-nexus-mcp

Add to ~/.claude/settings.json or project .mcp.json:

{
  "mcpServers": {
    "aaaa-nexus": {
      "command": "python",
      "args": ["-m", "aaaa_nexus_mcp"],
      "env": {
        "AAAA_NEXUS_API_KEY": "an_your_key_here",
        "AAAA_NEXUS_AUTOGUARD": "1"
      }
    }
  }
}

Restart the editor. All 140 tools are now available as nexus_* in your chat. See docs/ONBOARDING.md for the setup checklist and examples/mcp_configs/ for Cursor, Claude Desktop, VS Code, Zed, and Windsurf.

2. Python

pip install aaaa-nexus-mcp

import asyncio
from aaaa_nexus_mcp.client import NexusAPIClient

async def main():
    async with NexusAPIClient(api_key="an_...") as c:
        verdict = await c.post("/v1/oracle/hallucination",
                               {"text": "The moon is made of Swiss cheese."})
    print(verdict)  # {"verdict": "unsafe", "policy_epsilon": ..., "_guard": {...}}

asyncio.run(main())

Full script: examples/python_quickstart.py.

3. TypeScript / Node / Deno / Bun

npm install @atomadic/nexus-client

import { NexusClient } from "@atomadic/nexus-client";

const nexus = new NexusClient({ apiKey: process.env.AAAA_NEXUS_API_KEY });
const verdict = await nexus.oracle.hallucination({ text: "The moon is made of Swiss cheese." });
console.log(verdict);

Full script: examples/typescript_quickstart.ts. See docs/INTEGRATION.md for the broader client surface.

4. curl (any language)

curl -sS https://atomadic.tech/v1/oracle/hallucination \
  -H "Authorization: Bearer $AAAA_NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"The moon is made of Swiss cheese."}'

Full script: examples/curl_quickstart.sh.

---

Configuration

Variable	Default	Purpose
AAAA_NEXUS_API_KEY	(none)	Bearer token for paid tools
AAAA_NEXUS_BASE_URL	https://atomadic.tech	API base URL
AAAA_NEXUS_TIMEOUT	20.0	Request timeout (seconds)
AAAA_NEXUS_AUTOGUARD	1	Annotate every response with hallucination + drift verdicts

Free tier endpoints that work without a key: /health, /v1/rng/quantum, /v1/agent/card, /v1/metrics.

---

Documentation

• docs/ONBOARDING.md — fast-start setup by product lane, plus trust bootstrap order
• docs/INTEGRATION.md — language-by-language integration guide
• docs/TOOLS.md — tool index and pricing references for the 140-tool surface
• docs/LORA_REWARDS.md — rewards program, leaderboard, prize mechanics
• docs/TRUSTED_RAG.md — RAG cycle, provenance, receipt format
• docs/MCP_CLIENTS.md — editor-by-editor setup (Claude, Cursor, VS Code, Zed, Windsurf)

Examples

• examples/python_quickstart.py
• examples/typescript_quickstart.ts
• examples/curl_quickstart.sh
• examples/lora_flywheel.py — earn rewards loop
• examples/trusted_rag.py — provenance-gated retrieval
• examples/agent_self_gate.py — agent that gates its own commits
• examples/mcp_configs/ — drop-in configs for every MCP editor

License

Source package: MIT. Generated OpenAPI schema: CC BY-ND 4.0.

MIT applies to the contents of this repository: the Python package, MCP wiring, examples, and public docs shipped here. The hosted AAAA-Nexus service, backend implementation, models/proofs, pricing surfaces, and atomadic.tech site content are separate from this repository and may be separately licensed or proprietary. Atomadic, AAAA-Nexus, and related names, logos, and branding are not granted under MIT.