Using the Aegis MCP Server in Claude

Aegis exposes its internals to Claude over the Model Context Protocol (MCP). This is how a person — or an automated runner — reads routes, runs QA, audits pages and drives Nudger without opening a dashboard.

Because Aegis is a microservices architecture, the Admin worker acts as the single MCP edge router. It hosts its own tools and proxies the rest to internal workers over Cloudflare service bindings. You connect to one endpoint and get everything.

  • Endpoint: POST https://aegis.purdyandfigg.dev/api/mcp
  • Lovable-scoped endpoint: POST https://aegis.purdyandfigg.dev/api/mcp/lovable — a reduced tool set intended for Lovable's chat connector.
  • Transport: Streamable HTTP, stateless. Each request builds its own server instance, so there is no session affinity to worry about.

How to add Aegis to Claude

Aegis is already registered in the Claude organisation settings, so there are no JSON config files to edit:

  1. Open Claude.
  2. Go to Customise.
  3. Find Aegis Admin MCP Edge Router in the organisation tool list.
  4. Enable it.

Refreshing the tool list

Claude fetches the tool list at startup. If a tool exists in the code but not in your Claude session:

  1. Check it's deployed. Merging to main deploys the Admin worker; a local change isn't visible to Claude.
  2. Fully quit Claude (Cmd + Q on Mac — not just closing the window) and reopen.

Tool inventory

The Admin worker registers 29 tools directly and proxies 14 more from Nudger.

These counts drift whenever a tool is added, so verify rather than trust them — this one had, silently: it read 29 while the code held 28, and only came back into agreement when push_playbook_rule was added on 2026-09-09. Run the commands; do not trust the number above.

grep -cE '^\s+server\.tool\(' admin/src/mcpRouter.js      # direct
grep -cE 'addNudgerProxyTool\(' admin/src/mcpRouter.js     # proxied from Nudger

The authoritative list is whatever Claude shows after a restart.

Routes

Tool Does
list_routes Lists all configured routes and their proxy targets
lock_route Locks a route with a password so it can't be casually edited
unlock_route Unlocks a previously locked route

Code and page auditing

Tool Does
aegis_proxy_audit Checks React code for Aegis proxy compatibility (no iframes, basename set)
aegis_shopify_audit Checks React/HTML against the native-Shopify rules

Compliance scanning was removed from MCP on 2026-09-01. aegis_cap_audit and page_audit both scanned via Compliance AI, which was removed because it passes almost everything — an agent would have got a confident "no violations" from an engine that cannot fail a page. Run CAP scans from Admin instead (Edit Route → Monitor Configuration), which uses Passmark. Restoring the MCP tools is on the roadmap; it needs Passmark to accept raw copy, as its API currently takes a URL or a file.

QA test authoring

Tool Does
get_qa_test Retrieves the active test files for a route
get_route_prompt Returns route metadata, GA sections and the drafting instructions
get_next_testless_route Finds the next active route with no test baseline
create_qa_test Saves a new suite for a route (lands as preview)
update_qa_test Updates a test file; can optionally make it the active version

QA versioning and rollback

Tool Does
list_qa_test_versions Lists all versions of a test file
create_qa_test_version Snapshots all current test files as a new version
set_default_qa_test_version Makes a historical version the active baseline

set_default_qa_test_version and update_qa_test with make_default=true are the activation gate. Automated runners must not call them — see the QA Runner Operations Guide.

QA execution

Tool Does
get_next_qa_test_route Claims the next queued route and returns what to do with it
submit_qa_test_result Submits a run's status and Markdown report
setup_qa_runner_skill Returns the runner skill prompt, turning Claude into a QA runner
reset_qa_test_queue Resets every route in the queue back to pending
push_playbook_rule Proposes a rule learned in a run for the fleet-wide playbook. Does not take effect until a superadmin approves it in Settings → Playbook Rules. Dated and attributed to the run. Takes kind: 'replace' with replaces to CORRECT existing text rather than add to it, and page_type / store to scope a rule to part of the estate
list_playbook_proposals Lists proposals and their status — yours or everyone's. status: 'open' is what a human still has to decide
amend_playbook_proposal Corrects your own proposal while it is still pending. Use this rather than proposing a second, corrected version
withdraw_playbook_proposal Takes your own pending proposal back, with a reason. It stays on the record as withdrawn

A proposal is not the playbook. These three act only on proposals, only on your own, and only while nobody has decided — the superadmin gate is unchanged. An edit proposal removes text as well as adding it, so the review screen shows the removal and the approval warns about it separately.

Visual baselines

Tool Does
save_screenshot_baseline Saves a new visual baseline for a route
audit_screenshot Uploads a screenshot and diffs it against the active baseline

GA tracking configuration

Tool Does
list_ga_frameworks Lists global GA modules and their expected tracking attributes
get_route_ga_config Reads a route's GA expectations
update_route_ga_config Writes them — and regenerates that route's ga-tracking.test.md

Ecommerce

Tool Does
setup_ecom_template_skill Returns the rules for turning a live page into an Aegis ecommerce page template — capture with the SingleFile Chrome extension, clean up, register — plus the templates that already exist

Gated on ecommerce access, like the rest of the module.

Nudger (proxied via service binding)

Tool Does
nudger_card_state State of a Trello card by project code
nudger_todo_list_status Cards currently in the To Do list
nudger_overall_summary Card counts across all lists
nudger_run / nudger_status / nudger_list Run and inspect Nudger jobs
nudger_setup Registers a project with stakeholders and preview URL
nudger_scan_trello Rescans the board
nudger_read_trello_odt Reads an .odt design brief attachment
nudger_checkout_list_products Lists Shopify products (UK or US)
nudger_checkout_list_discounts Lists active discount codes
nudger_checkout_create Builds and saves a Shopify cart URL
nudger_checkout_list Lists saved checkouts and their routes
nudger_checkout_test Verifies a checkout URL responds

Prompts

Two MCP prompts serve the Lovable auto-fix rule sets, loaded from qabot_test_templates so they can be edited without a deploy:

  • lovable_proxy_autofixes — rules for Aegis-proxied React apps
  • lovable_shopify_autofixes — rules for native Shopify pages

Security status

⚠️ /api/mcp is currently unauthenticated. The Admin worker's auth middleware explicitly skips the /api/mcp path, and the MCP router's own bearer-token check is commented out and marked "temporarily disabled for testing". The endpoint is publicly reachable, so every tool above — including the Nudger tools that reach Shopify Admin and Trello — can be called by anyone who knows the URL.

This is a blocking item, tracked in the handover security notes. It must be closed before the MCP surface is widened to more people or more tools.