AAAA-Nexus MCP for Cursor

Agent infrastructure with formal safety guarantees, packaged as a Cursor plugin.
27 MCP tools · autonomous x402 micropayments · certified hallucination ceiling · CVE-2025-6514 mitigation · free tier to kick the tires.

Install · Tour · Examples · Tools · Costs · Troubleshooting · FAQ · License

Why this plugin

Most Cursor MCP plugins give your agent more tools. This one gives your agent safer tools.

	Typical MCP plugin	AAAA-Nexus MCP
Shape	"Here are some endpoints"	Skills that compose tools into safe, budgeted workflows
Authorization	Bearer token, trust the agent	Identity verify → RatchetGate session (CVE-2025-6514 mitigation) → per-action authorize → spending bound
Hallucination control	Classifier-based post-hoc check	Certified upper bound on confabulation probability from model geometry
Prompt injection defense	None / in-agent heuristics	AEGIS MCP-Sentinel — tool calls routed through prompt-injection-resistant proxy
Spending discipline	Manual budget tracking	Hard session cap (`$0.50` default) + `/nexus-budget` command + explicit expensive-tool guard
Evidence trail	Logs you have to parse	`lineage_record` + `uep_trace_certify` — tamper-proof hash chain
Payment	Your credit card on file	Autonomous x402 USDC on Base L2 — agents pay per-call, or API key
Secrets	README warns you to be careful	`aaaa-nexus-usage.mdc` rule file auto-loads in Atomadic-shaped repos and redacts bearer tokens
License	MIT/Apache, no moat	BUSL-1.1 — free for internal use, competing hosted platforms need a commercial license

Concrete test: can your MCP plugin (a) prove a tool call came from a verified agent, (b) block it before a prompt-injected response leaks, (c) cap the session spend at $0.50, and (d) produce a cryptographic receipt of the decision — in ten lines of chat?

This one can. Scroll to Examples.

Verification status

Every tool in this plugin has been exercised end-to-end against the live atomadic.tech server. 21 of 27 tools verified OK on the 2026-04-20 baseline (2 real calls each, real data captured); 6 carve-outs were transparent upstream issues (Vanguard endpoints 500; ratchet/proxy schema quirks). Full pass/fail matrix, real response shapes, and cost ledger live in TEST_REPORT.md.

Server fixes landed upstream (pending deploy). All 12 server-side findings from the E2E run have been patched in the AAAA-Nexus storefront:

Malformed JSON / wrong content-type now returns 400 invalid_json / 415 — not a generic 500. The root-cause anti-pattern was swept across ~68 call sites.
authorize_action, spending_authorize, contract_verify, and the federation handlers now return 400 with structured required / optional / hint fields instead of 200 OK bodies containing silent errors.
The AEGIS handlers now explicitly distinguish the two agent_id formats the API accepts (positive-integer string vs. DID string) in their error envelopes.
spending_authorize detects the amount_usdc vs amount_micro_usdc unit mismatch and returns a unit_mismatch_hint.
Every response now carries X-Request-Id (echoes client-supplied or synthesizes) and paid endpoints echo X-Price-Micro-USDC for observability. The x402 PAYMENT-REQUIRED header remains the authoritative price on 402.
New GET /v1/auth/whoami (free tier) reports auth state, tier, and quota snapshot without ever returning secrets.
Unknown paths now return 404 (previously 200 {"error":"not_found"}).

Post-deploy, re-run harness.ps1 to verify the P1 failures flip from 500 to 400 with actionable bodies. TEST_REPORT.md captures the pre-fix baseline; the carve-outs above are the pre-deploy state.

Install in 60 seconds

# 1. Clone (or copy) the plugin to Cursor's local plugins dir
git clone https://github.com/AAAA-Nexus/aaaa-nexus-plugin.git \
  ~/.cursor/plugins/local/aaaa-nexus-mcp

# 2. Set your API key (Windows shown; see Credential setup below for macOS/Linux)
setx AAAA_NEXUS_API_KEY "nxs_live_..."

# 3. Fully quit Cursor, then relaunch (reload-window is NOT enough)

Don't want a key? Skip step 2. The free tier gives 3 trial calls per endpoint per day and includes rng_quantum outright. You can probe the entire plugin before spending a cent.

Free tier vs paid, at a glance:

Free: 3 calls / endpoint / day. Each call has a mandatory ~2-second server-side pause — do not retry during it. Great for sanity checks and dev probes; painful in multi-step chains (5 × 2s = 10s).

Paid (API key or x402): instant, no pause, no daily cap. Use for any latency-sensitive workflow.

First run smoke test: in Cursor, ask:

Run the aaaa-nexus-get-started skill.

Expected: a quantum-seeded random payload with HMAC-SHA256 entropy proof, plus the canonical server manifest (name, version, mcpVersion). If that works, everything downstream works.

A guided tour

The plugin installs 7 skills, 2 rules, 1 command, and 1 MCP server into Cursor. Here's what each surface does and when it fires.

The MCP server

Declared in mcp.json. Remote HTTP transport to https://atomadic.tech/mcp with bearer auth and SSE streaming. No local binary, no stdio process — Cursor handles header env substitution.

{
  "mcpServers": {
    "aaaa-nexus": {
      "type": "http",
      "url": "https://atomadic.tech/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AAAA_NEXUS_API_KEY}",
        "X-Atomadic-Agent-Suite": "cursor-plugin-aaaa-nexus-mcp",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

The 7 skills — what, when, cost

Skills are model-invoked by description — you don't call them directly, Cursor's agent auto-picks the right one from your intent. Each skill composes multiple MCP tools into a safe workflow with failure modes, freshness guards, and minimum-cost hints.

#	Skill	Fires when you…	Cost floor	Highest tool
1	`aaaa-nexus-get-started`	first install or debug connectivity	$0.00	`rng_quantum` (free)
2	`aaaa-nexus-uep-govern`	work inside an Atomadic/UEP/ASS-ADE repo	$0.08	`sys_trust_gate` ($0.06)
3	`aaaa-nexus-agent-trust-chain`	build an agent with identity + budget	$0.20	`contract_verify` ($0.10)
4	`aaaa-nexus-aegis-edge`	need bounded/proxied tool execution	$0.016	`aegis_mcp_proxy_execute` ($0.008)
5	`aaaa-nexus-security-assurance`	red-team, compliance, or threat-score	$0.10	`vanguard_continuous_redteam` ($0.12)
6	`aaaa-nexus-vanguard-onchain`	MEV intent, wallet session, or escrow	$0.16	`vanguard_escrow_lock_and_verify` ($0.12)
7	`aaaa-nexus-evidence-pack`	RAG + summarize with provenance	$0.08	`rag_augment` ($0.04)

The 2 rules — posture, not workflow

Rules auto-load only inside Atomadic-shaped repos (globs: **/.ass-ade/**, **/AGENTS.md, **/.cursor/**, **/atomadic*/**). They don't duplicate skills — they encode posture.

Rule	Governs
`aaaa-nexus-usage.mdc`	Secret hygiene, logging redaction, 401/402/403 triage
`aaaa-nexus-payment-posture.mdc`	x402 flow, session budget cap ($0.50), expensive-tool guard

The 1 command — user-invoked

Command	What it does
`/nexus-budget`	Snapshot of session spend, credit pack balance, expensive-tool reminder, free-tier availability. Read-only — does not invoke paid tools.

Examples

Real prompts you can paste into Cursor right now. Costs shown are actual µUSDC, not estimates.

Example 1 — "Does it even work?" (free, 0 µUSDC)

You:

Is the aaaa-nexus MCP reachable and is my key working?

Cursor's agent: auto-invokes aaaa-nexus-get-started →

1. Fetches https://atomadic.tech/.well-known/mcp.json
   → server=aaaa-nexus v0.5.1, mcpVersion=2025-11-25, 27 tools  ✓
2. MCP tools/call rng_quantum
   → 200 OK with invocation contract:
     { url: "/v1/rng/quantum", method: "GET", paid: false }       ✓
3. Follows the URL (GET /v1/rng/quantum), waits ~2s free-tier pause
   → { random: 2423844373, format: "hex", product: "DCM-1001" } ✓
4. Reports:
   auth_path: api-key | x402 | free
   transport: OK
   cost_spent: 0 µUSDC

Never spends a cent. Perfect for CI probes (budget ~2s wall-clock per free call).

Example 2 — "Govern this UEP change before I ship it" ($0.30)

You (inside an Atomadic-shaped repo with .ass-ade/ present):

I just rewrote the autopoiesis-plan prompt. Run the full UEP cycle before I commit.

Cursor's agent: auto-invokes aaaa-nexus-uep-govern (rules auto-load), skill chains:

#	MCP tool	µUSDC	What it returns
1	`uep_preflight`	20,000	`friction: "low"`, proceed
2	`uep_context`	20,000	Context pack hash `ctx_7f4a…`
3	`uep_synthesis_guard`	40,000	`pass: true`, no ungrounded claims detected
4	`sys_trust_gate`	60,000	`verdict: PASS`, hallucination upper bound `0.031`
5	`sys_lint_gate`	40,000	`pass: true`, 0 policy violations
6	`uep_trace_certify`	60,000	Cryptographic receipt `trc_9a2e…`
7	`lineage_record`	60,000	Hash-chain entry `ln_c8b1…`
	total	300,000	= $0.30

Then it tells you: "Trust gate PASS. Trace certified. Safe to ship. Cost: $0.30 of your $0.50 cap — $0.20 remaining."

If any step fails (preflight friction=high, synthesis-guard catches ungrounded text, trust-gate FAIL), the skill aborts and tells you exactly which phase blocked. You don't spend the next step's µUSDC.

Example 3 — "Build an agent I can actually trust" ($0.20)

You:

Create an agent that searches GitHub, summarizes issues, and posts to Slack. It needs identity, session security against CVE-2025-6514, and a spending cap.

Cursor's agent: auto-invokes aaaa-nexus-agent-trust-chain:

1. identity_verify  →  topological proof: agent = did:atomadic:0xa1b2…    80,000 µUSDC
2. ratchet_register →  47-epoch RatchetGate session sid_f00d             20,000 µUSDC
   (rotates every tool call — stolen bearer tokens useless after 1 epoch)
3. authorize_action →  tool-call gate token for "search github"           60,000 µUSDC
4. spending_authorize → $2.00 max per day, trust-decay bound              40,000 µUSDC
                                                              total: 200,000 µUSDC = $0.20

The agent is now bound to:

a verified identity,
a session that auto-rotates (CVE-2025-6514: the session credential theft vuln that hit a whole class of MCP integrations in mid-2025),
a per-action authorization gate, and
a budget ceiling the agent cannot exceed.

For cross-platform handoff (e.g. to an OpenAI Assistants session), add federation_mint ($0.08). For formal-bounds policy claim check before a high-stakes tool call, add contract_verify ($0.10).

Example 4 — "Route every tool call through a sentinel" ($0.016)

You:

Before my agent calls stripe_create_charge, I want the call inspected for prompt injection and the generation entropy bounded. Cheapest possible.

Cursor's agent: auto-invokes aaaa-nexus-aegis-edge:

1. aegis_router_epistemic_bound    8,000 µUSDC
   → generation entropy 0.42 (ceiling 0.75) ✓, confidence 0.87 (floor 0.60) ✓
   → verdict: PASS
2. aegis_mcp_proxy_execute         8,000 µUSDC
   → sentinel scans downstream_args for injection signatures, none found
   → verdict: PASS
   → invokes stripe_create_charge through the proxy
                                   total: 16,000 µUSDC = $0.016

At $0.016 per gated call, this is the cheapest safety-critical primitive in the suite. For comparison, one contract_verify costs $0.10 — you can gate 6 tool calls through AEGIS for the price of one formal bounds check. Use AEGIS liberally.

Example 5 — "Certified hallucination ceiling on this answer" ($0.04)

You:

Before I quote this to the customer, give me the mathematical upper bound on how much of this answer could be confabulated.

Cursor's agent: auto-invokes aaaa-nexus-security-assurance → hallucination_oracle:

hallucination_oracle                40,000 µUSDC
→ hallucination_upper_bound: 0.042
   (model class: mid-2026 composer-2, corpus: general web)
   "At most 4.2% of tokens in the answer can be confabulated
    given the model's geometry and grounding density."

This is not a classifier. It's a certified upper bound derived from model-class geometry and grounding density — i.e. a mathematical ceiling, not a heuristic guess. Pair with threat_score (+$0.06) if the payload itself needs scoring.

Add vanguard_continuous_redteam ($0.12) for dedicated adversarial rehearsal — but that's a dedicated audit-session spend, not per-query.

Example 6 — "On-chain agent with MEV shield and escrow" ($0.28)

You:

My agent needs to swap 100 USDC → ETH on Base, but I want MEV-shielded and the output escrowed until it clears my slippage bound.

Server status (2026-04-20 baseline): on the E2E run, the four Vanguard MCP endpoints (vanguard_wallet_govern_session, vanguard_mev_route_intent, vanguard_escrow_lock_and_verify, vanguard_continuous_redteam) returned 500 INTERNAL SERVER ERROR on every payload — see TEST_REPORT.md. Server-side fix has landed upstream (JSON-parse anti-pattern replaced with parse_json_body + from_value_shape helpers across all handlers; these four now return 400 with structured required / optional / hint fields on bad input, and 200 with real payloads on valid input). Plugin behaviour unchanged; re-run the harness after the next server deploy to flip this box to green. The surrounding identity/spending/escrow flows work end-to-end.

Cursor's agent: auto-invokes aaaa-nexus-vanguard-onchain:

#	Tool	µUSDC	What
1	`vanguard_wallet_govern_session`	40,000	UCAN wallet session (depth=2, max=$200/day)
2	`spending_authorize`	40,000	Trust-decay bound: OK at $0.01 / $0.50 session cap
3	`vanguard_mev_route_intent`	80,000	Shield bundle orchestrated, survivability 97%
4	(agent submits swap bundle)	—	On-chain execution — plugin doesn't sign
5	`vanguard_escrow_lock_and_verify`	120,000	Escrow locked, contract validated, release gate set on slippage ≤ 0.3%
	total	280,000	= $0.28

Add vanguard_continuous_redteam (+$0.12) only when rehearsing adversarial MEV, not per-tx. The richer escrow lifecycle (/v1/escrow/create|release|dispute|status) lives in the HTTP annex.

Example 7 — "Summarize this 40-page RFP with provenance" ($0.08)

You:

Here's a 40-page RFP PDF. Give me the requirements list with a hash-provenance entry per requirement so audit can verify each one.

Cursor's agent: auto-invokes aaaa-nexus-evidence-pack:

1. rag_augment       40,000 µUSDC   → 12 passages, each with provenance hash
2. text_summarize    40,000 µUSDC   → extractive summary, bounded to input
                       total: 80,000 µUSDC = $0.08

Returns a structured object:

{
  "passages": [
    { "text": "Vendor must support SAML 2.0 (section 4.2)",
      "provenance_hash": "sha256:7f4a…" },
    // …11 more
  ],
  "summary": "Top 12 requirements grouped by theme: auth, data, SLA, pricing.",
  "total_cost_micro_usdc": 80000
}

Then chain through aaaa-nexus-uep-govern for uep_synthesis_guard + sys_trust_gate (+$0.10) if you want ship-ready certified evidence.

Example 8 — "How much have I spent?" (free, always)

You:

/nexus-budget

Cursor's agent: runs the /nexus-budget command — zero paid calls:

AAAA-Nexus budget
  Session spend:        324,000 µUSDC ($0.324)
  Session cap:          500,000 µUSDC ($0.500)
  Remaining:            176,000 µUSDC ($0.176)
  Credit pack balance:  7,340,000 µUSDC ($7.34)
  Auth mode:            api-key

  Expensive tools (would breach cap if chained):
    - contract_verify                       100,000 µUSDC
    - vanguard_continuous_redteam           120,000 µUSDC
    - vanguard_escrow_lock_and_verify       120,000 µUSDC

  Free probes available:
    - rng_quantum                           0 µUSDC (3/day free tier)
    - 3 daily free trial calls per endpoint

The agent reads this before proposing any expensive call. If a planned call would breach the cap, the plugin stops and surfaces options: raise cap, switch to free probe, or abort. No surprise bills.

The complete tool surface

27 MCP tools from AAAA-Nexus v0.5.1 (mcpVersion 2025-11-25). Grouped by family, with the skill that composes each one.

🏛 UEP governance (10 tools) — Atomadic preflight, synthesis guard, trust/lint gates, lineage, trace certification.

Tool	µUSDC	Skill
`uep_preflight`	20,000	`aaaa-nexus-uep-govern`
`uep_context`	20,000	`aaaa-nexus-uep-govern`
`uep_synthesis_guard`	40,000	`aaaa-nexus-uep-govern`
`uep_aha_detect`	30,000	`aaaa-nexus-uep-govern`
`uep_trace_certify`	60,000	`aaaa-nexus-uep-govern`
`uep_autopoiesis_plan`	20,000	`aaaa-nexus-uep-govern`
`sys_trust_gate`	60,000	`aaaa-nexus-uep-govern`
`sys_lint_gate`	40,000	`aaaa-nexus-uep-govern`
`lineage_record`	60,000	`aaaa-nexus-uep-govern`
`sys_constants`	4,000	multiple

🔐 Identity + trust chain (6 tools) — Verify principals, bind sessions (RatchetGate / CVE-2025-6514), per-action authorization, federation, formal contract verification.

Tool	µUSDC	Skill
`identity_verify`	80,000	`aaaa-nexus-agent-trust-chain`
`ratchet_register`	20,000	`aaaa-nexus-agent-trust-chain`
`authorize_action`	60,000	`aaaa-nexus-agent-trust-chain`
`spending_authorize`	40,000	`aaaa-nexus-agent-trust-chain` · `aaaa-nexus-vanguard-onchain`
`federation_mint`	80,000	`aaaa-nexus-agent-trust-chain`
`contract_verify`	100,000	`aaaa-nexus-agent-trust-chain`

🛡 AEGIS (2 tools) — Epistemic-bound router + MCP-Sentinel proxy. Cheapest safety primitives ($0.008 each).

Tool	µUSDC	Skill
`aegis_router_epistemic_bound`	8,000	`aaaa-nexus-aegis-edge`
`aegis_mcp_proxy_execute`	8,000	`aaaa-nexus-aegis-edge`

🔬 Security assurance (3 tools + 1 free) — Certified hallucination ceiling, threat score, continuous red-team, free quantum-seeded audit entropy.

Tool	µUSDC	Skill
`rng_quantum`	0 (free)	`aaaa-nexus-get-started` · `aaaa-nexus-security-assurance`
`hallucination_oracle`	40,000	`aaaa-nexus-security-assurance`
`threat_score`	60,000	`aaaa-nexus-security-assurance`
`vanguard_continuous_redteam`	120,000	`aaaa-nexus-security-assurance`

⛓ Vanguard on-chain (3 tools) — UCAN wallet governance, MEV-shield routing, escrow lock-and-verify (Base L2).

Tool	µUSDC	Skill
`vanguard_wallet_govern_session`	40,000	`aaaa-nexus-vanguard-onchain`
`vanguard_mev_route_intent`	80,000	`aaaa-nexus-vanguard-onchain`
`vanguard_escrow_lock_and_verify`	120,000	`aaaa-nexus-vanguard-onchain`

📚 RAG + text (2 tools) — Retrieve-and-quote with provenance, bounded extractive summary.

Tool	µUSDC	Skill
`rag_augment`	40,000	`aaaa-nexus-evidence-pack`
`text_summarize`	40,000	`aaaa-nexus-evidence-pack`

Beyond MCP: each skill's ## HTTP annex section documents ~30 additional HTTP-only endpoints (ratchet lifecycle, UCAN delegation, DeFi risk scoring, EU AI Act compliance, VRF draws, SLA registration) for flows not yet MCP-exposed.

Cost map

Prices in µUSDC (1,000,000 µUSDC = $1.00). Source of truth: https://atomadic.tech/.well-known/mcp.json.

Cheapest first

  free     ████  rng_quantum                         (3/day free tier)
  4,000    ████  sys_constants
  8,000    ████  aegis_router_epistemic_bound
  8,000    ████  aegis_mcp_proxy_execute
 20,000    ████  ratchet_register
 20,000    ████  uep_preflight · uep_context · uep_autopoiesis_plan
 30,000    ████  uep_aha_detect
 40,000    ████  rag_augment · text_summarize · spending_authorize ·
                 hallucination_oracle · sys_lint_gate · uep_synthesis_guard ·
                 vanguard_wallet_govern_session
 60,000    ████  authorize_action · lineage_record · sys_trust_gate ·
                 threat_score · uep_trace_certify
 80,000    ████  federation_mint · identity_verify · vanguard_mev_route_intent
100,000    ████  contract_verify                     ⚠ expensive
120,000    ████  vanguard_continuous_redteam         ⚠ expensive
120,000    ████  vanguard_escrow_lock_and_verify     ⚠ expensive

Typical-session cost (against the default $0.50 cap)

Workflow	Example tools	Cost
Install check	`rng_quantum`	$0.00
Minimal UEP	preflight + context + guard	$0.08
Ship-ready UEP	full 7-tool cycle	$0.30
Agent trust chain	identity + ratchet + authorize + spending	$0.20
Trust chain + contract	+ `contract_verify`	$0.30
AEGIS gate pair	both aegis tools	$0.016
Security min	hallucination + threat	$0.10
Security + red-team	+ continuous red-team	$0.22
On-chain min	wallet + spending + MEV	$0.16
On-chain + escrow	+ escrow lock	$0.28
Evidence pack	`rag_augment` + `text_summarize`	$0.08

Session budget cap is $0.50 by default — set in rules/aaaa-nexus-payment-posture.mdc. Running two $0.12 tools back-to-back with a chain in between will trip the cap; that's intentional, and /nexus-budget tells you before it happens.

Credential setup

Two valid auth paths. Pick one; don't mix inside a session.

Option A — API key (recommended for most users)

Buy a credit pack at https://atomadic.tech/pay — $8 = 500 calls, credits never expire.

Set AAAA_NEXUS_API_KEY at the OS/user level, not in a repo .env:

OS	How
Windows	`setx AAAA_NEXUS_API_KEY "nxs_live_..."` in PowerShell, then close the terminal
macOS	Add `export AAAA_NEXUS_API_KEY=nxs_live_...` to `~/.zshrc`, then `source ~/.zshrc` and launch Cursor from that terminal
Linux	Same as macOS with your preferred shell rc file

Fully quit Cursor (menu → Quit, not just reload-window) and relaunch. Cursor only reads env vars from its parent process at launch.

Verify: echo $AAAA_NEXUS_API_KEY (macOS/Linux) or $env:AAAA_NEXUS_API_KEY (PowerShell) should print your key.

Option B — x402 autonomous

Configure a Base L2 wallet with a small USDC balance. The plugin's rules/aaaa-nexus-payment-posture.mdc governs how the agent:

Calls the MCP tool normally.
Reads the 402 response's X-Payment-Required header (amount µUSDC, wallet, chain).
Checks session budget.
Signs a USDC payment on Base L2 (chain id 8453).
Retries with X-PAYMENT: <receipt>.
Optionally verifies via POST /v1/pay/verify.

Never cache receipts — each is single-use. Never commit wallet keys or payment proofs.

Troubleshooting

Symptom	Likely cause	Fix
MCP server not visible in Cursor → Settings → MCP	Plugin not loaded	Confirm folder at `~/.cursor/plugins/local/aaaa-nexus-mcp/`. Fully restart Cursor.
401 Unauthorized on every call	Key not in Cursor's parent-process env	Set at OS/user level (not repo `.env`). Fully quit + relaunch Cursor.
402 PAYMENT-REQUIRED from a paid HTTP endpoint	Expected if no API key	Follow `rules/aaaa-nexus-payment-posture.mdc`. Note: the MCP call itself returns 200 with an invocation contract; the 402 happens when you follow the contract's URL.
403 Forbidden	Suite header or account entitlement	Verify `X-Atomadic-Agent-Suite: cursor-plugin-aaaa-nexus-mcp` in `mcp.json`. Check account has access to the tool family.
400 `invalid_json` / 415 on a paid endpoint	Malformed body or wrong `Content-Type`	Send `Content-Type: application/json` and a well-formed JSON body. The error envelope includes a `hint` + `parse_error` showing the exact problem.
400 `invalid_request_shape`	Body is valid JSON but fails schema	Read the `parse_error` field — it names the missing/wrong-typed field. Cross-check against the skill's "minimum-valid shape" hint.
400 with `unit_mismatch_hint` on `spending_authorize`	Sent `amount_usdc` (decimal dollars) instead of `amount_micro_usdc` (integer µUSDC)	Multiply by 1,000,000 and resend as `amount_micro_usdc`.
400 `invalid_agent_id` on an AEGIS tool	AEGIS wants a positive-integer string (`"42"`); other families want a DID string (`"did:atomadic:..."`)	Check the skill's request-shape hint; the error envelope lists the required format.
429 Rate limit	Free-tier daily cap (3/endpoint/day) or retrying during the 2s pause	Wait the full 2s between free calls, or add an API key for instant responses.
~2s hang on a free call	Expected free-tier pause	This is not a bug — the server rate-limits free calls with a deliberate pause. Paid calls are instant.
Tool missing from `tools/list`	Server drift	Compare against https://atomadic.tech/.well-known/mcp.json. Skill files pin `v0.5.1` / `mcpVersion 2025-11-25`.
Budget-cap breach surprise	Session spend un-tracked	Run `/nexus-budget` between chains; the command is always free.
Skill won't auto-invoke	Description/path mismatch	Check the skill's `paths` globs match your repo shape, or invoke explicitly: "Run the `<skill-name>` skill."
Red-team or escrow tool unexpectedly charged	No cap confirmation	These tools cost $0.10–$0.12 each. `payment-posture.mdc` requires explicit budget confirmation. If skipped, file an issue.

FAQ

Is this affiliated with Atomadic?

The plugin is not an "official" Atomadic product in the sense of being vendor-supported — it's a Cursor packaging of the hosted AAAA-Nexus service at https://atomadic.tech. The service itself is operated by Atomadic. See NOTICE.

Do I need an API key to try it?

No. rng_quantum is in the server's free-tier allow-list, and every paid endpoint gives you 3 free trial calls per day. You can fully evaluate the plugin before spending anything.

Caveat: free calls have a mandatory ~2-second server-side pause before responding. That's a deliberate rate-limit, not a bug — do not retry during the pause. Great for sanity-checks, slow for chains (five free calls in a row = ~10s of pause). Paid calls (API key or x402) are instant.

Why is `rng_quantum` slow to return?

Free-tier calls pause ~2 seconds server-side before responding. It's a rate-limit mechanism, not a network problem. Either (a) accept the pause for probes and single calls, or (b) add an API key — paid calls are instant.

Do paid tools return HTTP 402 on the MCP call?

No — that's a common misconception. AAAA-Nexus uses an invocation-contract pattern. The MCP tools/call always returns 200 OK with a structured contract: {url, method, paid, price_micro_usdc, pricing_doc}. You then follow the url. That HTTP request is where a paid endpoint responds 402 PAYMENT-REQUIRED. The challenge header is literally PAYMENT-REQUIRED; the signature header is PAYMENT-SIGNATURE (alias X-402-Payment). Full flow in rules/aaaa-nexus-payment-posture.mdc.

How do I debug auth / quota without spending anything?

Call GET /v1/auth/whoami — free tier, no paid tools invoked. It reports:

authenticated — whether the API key you sent is known to the server,
api_key.{present, shape_valid, known, tier, issued_at} — safe metadata only, never the key itself,
free_tier.sample_path_calls_used_today — quota snapshot (does not increment your counter),
payment.{x402_supported, api_key_header, upgrade_url} — where to pay if you need to.

Use this when the plugin's own aaaa-nexus-get-started skill reports auth_path: free but you know you set a key — whoami will tell you if the key made it into Cursor's parent-process env, passed shape validation, and is registered server-side.

What are the `X-Request-Id` and `X-Price-Micro-USDC` headers?

Every response from atomadic.tech now carries:

X-Request-Id — a correlation id. If you send one on the request, the server echoes it back; otherwise the server synthesizes one. Useful for matching a failing call to your own logs, or for asking support a specific question.
X-Price-Micro-USDC — the list price of the endpoint in µUSDC, informational only. The authoritative price on a 402 response is still the PAYMENT-REQUIRED challenge header — this is just a convenience for client-side budget tracking.

Both are safe to ignore if you don't need them. Set $env:DEBUG_METERING = "1" and /nexus-budget will surface the request ids for your session.

What is CVE-2025-6514 and how does RatchetGate help?

CVE-2025-6514 is a class of MCP session-credential-theft issues disclosed in mid-2025 affecting integrations that treated a long-lived bearer token as an agent's session identity. RatchetGate rotates a session key on each tool call within a 47-epoch window, so even if an attacker captures a bearer token, it's useless after one epoch. Register a session with ratchet_register ($0.02), then use the session id for subsequent calls. See aaaa-nexus-agent-trust-chain.

How is the "certified hallucination ceiling" different from a classifier?

A classifier gives you a probability estimate based on training. hallucination_oracle gives you an upper bound derived from the model's geometry and the grounding density of the context — i.e. a mathematical ceiling ("at most X% of tokens can be confabulated given the model class and grounding") rather than a learned guess. It's more conservative and has audit-usable semantics.

Why BUSL-1.1 instead of MIT/Apache?

Internal use is free for any organization, including for-profits. BUSL-1.1 only requires a commercial license if you're reselling the plugin as a hosted platform / marketplace listing / competing MCP gateway. Auto-converts to Apache 2.0 on 2030-04-20. See docs/COMMERCIAL.md for plain-English examples of what's free vs what needs a commercial license.

Can the agent run up a huge bill?

Short answer: no, not without your consent. The default session cap is $0.50. The three expensive tools (contract_verify, vanguard_continuous_redteam, vanguard_escrow_lock_and_verify — each $0.10–$0.12) are guarded by an explicit expensive-tool check in rules/aaaa-nexus-payment-posture.mdc. The agent surfaces the cost and asks before proceeding.

If you want to raise the cap: tell the agent, e.g. "Raise the session cap to $2." The rule file honors explicit user requests to raise caps.

Does the plugin work with Claude Code?

Yes — the plugin dual-publishes via .claude-plugin/plugin.json. Basic compatibility is expected; report any issues on GitHub.

What's in the "HTTP annex" sections of each skill?

~30 endpoints on the AAAA-Nexus server aren't yet exposed as MCP tools (ratchet lifecycle, UCAN delegation, richer DeFi, EU AI Act compliance, VRF, SLA). Each skill documents the HTTP paths for the flows it supports, clearly labeled "not in MCP" so the agent doesn't fabricate tool names. See e.g. aaaa-nexus-agent-trust-chain/SKILL.md#http-annex.

Can I self-host the MCP server instead of using atomadic.tech?

The server is the upstream stdio MCP package: pip install aaaa-nexus-mcp. This plugin wraps the hosted HTTP endpoint; for self-host, replace mcp.json's HTTP transport with a stdio command pointing at the local package. (The hosted endpoint is recommended for most Cursor users — simpler, no local dependencies, and you still own your key.)

Where do I report issues or suggest new skills?

github.com/AAAA-Nexus/aaaa-nexus-plugin/issues. See CONTRIBUTING.md for skill-authoring conventions if you want to contribute a PR.

Architecture at a glance

                       ┌─────────────────────────────┐
        Cursor chat ──▶│     Cursor agent (model)     │──▶ picks skill by description
                       └──────────────┬───────────────┘
                                      │
        auto-loads in Atomadic repos  ▼
        ┌───────────────────────────────────────────────┐
        │ rules/aaaa-nexus-usage.mdc                     │
        │ rules/aaaa-nexus-payment-posture.mdc           │
        │   · secret hygiene  · 401/402/403 triage       │
        │   · session budget cap ($0.50)                 │
        │   · expensive-tool guard                       │
        └─────────────────────┬──────────────────────────┘
                              │
    skill picks tools ────────▼───────────────────────────
    ┌──────────────┬───────────────────┬────────────────┐
    │ get-started  │ uep-govern        │ trust-chain    │
    │ aegis-edge   │ security-assurance│ vanguard       │
    │ evidence     │  ← /nexus-budget  │  (command)     │
    └──────┬───────┴────────┬──────────┴───────┬────────┘
           │                │                  │
           ▼                ▼                  ▼
    ┌─────────────────────────────────────────────────┐
    │  mcp.json — HTTP + SSE                           │
    │  Bearer ${env:AAAA_NEXUS_API_KEY}                │
    │  X-Atomadic-Agent-Suite: cursor-plugin-aaaa-...  │
    └─────────────────────┬────────────────────────────┘
                          │ HTTPS
                          ▼
               https://atomadic.tech/mcp
                  27 tools · v0.5.1 · mcpVersion 2025-11-25
                     └─▶ x402 USDC on Base L2 (chain 8453)

Full detail: docs/ARCHITECTURE.md.

Canonical references

Thing	URL
Server manifest (truth)	https://atomadic.tech/.well-known/mcp.json
OpenAPI spec (146+ endpoints)	https://atomadic.tech/openapi.json
A2A agent card	https://atomadic.tech/.well-known/agent.json
Upstream MCP server source	https://github.com/AAAA-Nexus/aaaa-nexus-mcp
This plugin's source	https://github.com/AAAA-Nexus/aaaa-nexus-plugin
Pricing / credit packs	https://atomadic.tech/pay

If any of the above disagrees with this README, the server manifest wins and the plugin docs are stale — file an issue.

Documentation map

docs/CHEATSHEET.md — one-page quick reference (install, intent → skill, triage)
docs/ARCHITECTURE.md — transport, inventory, routing, cost map, evolution path
docs/COMMERCIAL.md — BUSL-1.1 plain-English guide + commercial license intake template
CHANGELOG.md — v0.1.0 detail + known limitations
CONTRIBUTING.md — skill authoring checklist, cost discipline, release flow
NOTICE — third-party attributions
LICENSE — BUSL-1.1 with internal-use-free Additional Use Grant

Licensing

Business Source License 1.1 — internal use is free, including inside for-profit companies. Auto-converts to Apache 2.0 on 2030-04-20.

Free without payment

Personal, academic, and educational use.
Internal use by any company — for-profits included — for development, CI/CD, security review, production workflows.
Contractors / consultants / employees using the plugin in paid work for an org that uses it internally.
Bundling inside a larger product, as long as that product is not a Prohibited Use.

Requires a commercial license from Atomadic

Offering the plugin as a hosted / managed / "as-a-service" product to third parties.
Listing on a plugin / app marketplace as your own product.
Operating as part of an agent platform / marketplace / AI infrastructure service / commercial MCP gateway.
Building any product whose primary value is exposing, reselling, or proxying AAAA-Nexus, NEXUS AEGIS, NEXUS VANGUARD, RatchetGate, or the AAAA-Nexus MCP server.
Operating any commercial service that competes with Atomadic's products at https://atomadic.tech.

Full plain-English guide + intake template: docs/COMMERCIAL.md.

Not affiliated

This plugin is an independent Cursor packaging of the AAAA-Nexus hosted service. The AAAA-Nexus service is operated by Atomadic at https://atomadic.tech. "AAAA-Nexus", "NEXUS AEGIS", "NEXUS VANGUARD", "RatchetGate", and "Atomadic" are trademarks of Atomadic; see NOTICE.

_{Built for agents that pay their way and show their work.}

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.claude-plugin		.claude-plugin
.cursor-plugin		.cursor-plugin
assets		assets
commands		commands
docs		docs
rules		rules
skills		skills
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
mcp.json		mcp.json

Folders and files

Latest commit

History

Repository files navigation

AAAA-Nexus MCP for Cursor

Why this plugin

Verification status

Install in 60 seconds

A guided tour

The MCP server

The 7 skills — what, when, cost

The 2 rules — posture, not workflow

The 1 command — user-invoked

Examples

Example 1 — "Does it even work?" (free, 0 µUSDC)

Example 2 — "Govern this UEP change before I ship it" ($0.30)

Example 3 — "Build an agent I can actually trust" ($0.20)

Example 4 — "Route every tool call through a sentinel" ($0.016)

Example 5 — "Certified hallucination ceiling on this answer" ($0.04)

Example 6 — "On-chain agent with MEV shield and escrow" ($0.28)

Example 7 — "Summarize this 40-page RFP with provenance" ($0.08)

Example 8 — "How much have I spent?" (free, always)

The complete tool surface

Cost map

Cheapest first

Typical-session cost (against the default $0.50 cap)

Credential setup

Option A — API key (recommended for most users)

Option B — x402 autonomous

Troubleshooting

FAQ

Architecture at a glance

Canonical references

Documentation map

Licensing

Free without payment

Requires a commercial license from Atomadic

Not affiliated

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages