aaaa-nexus-mcp

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:

• Prove its outputs aren't hallucinated.
• Detect drift before it compounds.
• Share a LoRA adapter with the rest of the swarm.
• Earn rewards when its fixes train the next model.
• Pull trusted RAG context with provenance receipts.
• Gate its own commits on a tamper-evident lint + trust score.
• Escrow a payment on outcome-based delivery.
• 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.