Intelligence Layer

One governed door in front of your data, with every AI agent behind it — a capability registry, scope checks, and an append-only audit trail, plus an MCP server so Claude or Cursor can use it directly.

You have data in Xano and a growing number of AI agents that want it. Handing each agent database access or vendor API keys does not scale, and it leaves you with no answer to the only three questions that matter in an incident: who asked, were they allowed, and what happened.

This template is that one door. An agent names a capability — orders.search, weather.forecast — and the layer identifies the caller, checks their scopes, forwards the call to whichever workspace or third-party API actually holds the data, and writes an append-only receipt. Agents never hold a downstream credential and never learn the topology. It runs end to end in about four minutes with no third-party credentials: the router uses Xano's free built-in model, the outside calls go to keyless public APIs, and the "downstream system" is a reference API group in the same workspace, reached over real HTTP. That also means a fresh install starts open — setting the two security switches is the first thing you do, and GET health tells you when you are done.

The code is prefixed xil_ throughout (for Xano intelligence layer), which is what the layer is called inside Xano. It is the same thing this page calls the gateway.

Once more than one agent needs company data, the usual options both fail. Give each agent a database connection or a vendor API key and you have copied your credentials across every consumer, with no way to revoke one of them and no record of what any of them did. Put a bespoke endpoint in front of each use case and the access rules end up spread across a dozen stacks, each slightly different, each a place governance can be wrong.

This template removes that by making the access decision a single piece of code and the routing a table. Every call — from the console, from curl, from Claude, from an agent tool — goes through one function, xil_proxy_request, which resolves the capability in the xil_capability registry, checks the caller's scopes, attaches the downstream credential the caller never sees, and appends a row to xil_audit_log whether the call was allowed, denied, mocked, or failed. Adding a capability is inserting a row, not shipping a deploy; anything not in the registry is not callable; and because the audit row is written on the same path as the call, the record cannot drift from what actually happened.

backend/
  ai/
    agent/
      xil_router.xs
    mcp_server/
      xil_gateway.xs
    tool/
      xil_country_info.xs
      xil_delivery_weather.xs
      xil_fx_convert.xs
      xil_get_client.xs
      xil_list_branches.xs
      xil_mcp_call_capability.xs
      xil_mcp_list_capabilities.xs
      xil_mcp_recent_audit.xs
      xil_mcp_resolve_intent.xs
      xil_open_ticket.xs
      xil_rep_performance.xs
      xil_search_orders.xs
      xil_warehouse_search.xs
  api/
    xil_admin/
      agents/
        register_post.xs
      api_group.xs
      health_get.xs
      seed_post.xs
    xil_app/
      api_group.xs
      ask_post.xs
      audit_get.xs
      capabilities_get.xs
      history_get.xs
      steps_get.xs
    xil_auth/
      api_group.xs
      login_post.xs
      me_get.xs
      signup_post.xs
    xil_layer/
      api_group.xs
      ask_post.xs
      audit_get.xs
      capabilities_get.xs
      proxy_post.xs
      resolve_post.xs
      steps_get.xs
    xil_source_reference/
      branches/
        list_get.xs
      clients/
        get_post.xs
      orders/
        search_post.xs
      reps/
        performance_post.xs
      api_group.xs
      health_get.xs
  function/
    xil_agent_from_key.xs
    xil_build_target_url.xs
    xil_check_auth.xs
    xil_check_scope.xs
    xil_city_coords.xs
    xil_current_turn.xs
    xil_emit_step.xs
    xil_extract_tool_calls.xs
    xil_header.xs
    xil_mock_response.xs
    xil_proxy_request.xs
    xil_ref_check_source_key.xs
    xil_resolve_caller.xs
    xil_resolve_capability.xs
    xil_run_ask.xs
    xil_seed_data.xs
    xil_source_key.xs
    xil_write_audit.xs
  table/
    ref_branch.xs
    ref_client.xs
    ref_paper_order.xs
    ref_sales_rep.xs
    xil_agent_key.xs
    xil_agent.xs
    xil_audit_log.xs
    xil_capability.xs
    xil_chat_step.xs
    xil_request_log.xs
    xil_user.xs
  workflow_test/
    agent_key_identifies_its_caller_and_can_be_revoked.xs
    failed_call_errors_instead_of_faking_data.xs
    governed_call_is_forwarded_and_audited.xs
    health_reports_the_layer_is_seeded_and_wired.xs
    intent_resolves_to_a_capability_without_a_model.xs
    scope_denied_call_is_logged_not_forwarded.xs
    seeded_source_data_answers_for_real.xs
    unknown_capability_is_refused_and_audited.xs
  workspace/
    xil.xs

 browser user ── username/password ──► /api:xil-auth ──► /api:xil-app ─┐
 agent / MCP client / curl ── X-Agent-Key ──► /api:xil-layer ─────────┤
                                                                      ▼
 POST /api:xil-{app,layer}/ask ──► xil_router (xano-free) ─► tool ┐
 POST /api:xil-layer/proxy ────────────────────────────────────┤
 MCP  xil_mcp_call_capability ─────────────────────────────────┤
                                                               ▼
                                                   xil_proxy_request
                                   resolve capability → check scope → call → audit → step
                                        │                                   │
                       transport "source"                     transport "external"
                                        ▼                                   ▼
                 <base>/api:xil-source-reference/…        Open-Meteo · CountriesNow
                 (this workspace in the demo,              open.er-api · DummyJSON
                  your source workspaces in production)    JSONPlaceholder (the only write)

1. Identify the caller. Browser users sign up or log in through xil-auth; Xano hashes their password and issues a one-day token. Machine callers send an agent key (X-Agent-Key, or Authorization: Bearer xil_…) to xil-layer; xil_resolve_caller hashes it and looks it up. The raw key is never stored: what is kept is its SHA-256 hash plus a short, non-secret prefix so an operator can tell keys apart.
2. Open a turn. POST ask registers a turn in xil_request_log, runs the router agent, and returns the answer with its tool calls, tool errors, and live steps. Browser turns carry user_id, and the app's history, step, and audit queries enforce that owner.
3. Resolve, check, forward, record. Every tool is one call to xil_proxy_request, the single chokepoint. It looks the capability up in xil_capability, checks the caller's scopes (*:*, service:*, service:operation), builds the target URL, attaches the right downstream credential, calls it, and appends an audit row.
4. Narrate it. xil_emit_step writes progress to xil_chat_step so a UI can show the turn as it runs (GET steps).

Scopes use a three-level grammar: *:* (everything), service:* (a whole service), service:operation (one capability). xil_check_scope is a pure function — no logging, no side effects — so the decision is easy to read and easy to test.

Multi-workspace routing lives in three columns on xil_capability: base_url (which instance answers), target_canonical (which API group there), and credential_ref (the name of the environment variable holding that workspace's key). Callers see none of it — the capability name is the whole interface, and the audit row is identical no matter which workspace answered.

Intent resolution is layered on purpose. The LLM picks tools when there is an LLM; POST resolve and the MCP xil_mcp_resolve_intent tool map free text to a capability using keyword rules with no model and no credentials at all, which is what keeps the registry usable from scripts, tests, and offline demos.

Mock data and failure are deliberately not the same thing

MOCK_MODE=true (or force_mock inside a workflow test) makes every capability serve a canned response. That is an explicit request for fake data, and mode says mock. The variable is not shipped — add it in the dashboard when you want it, since unset already means off.

A live call that times out or returns a bad status is not silently replaced with canned data. It returns __error with data: null, and an audit row of outcome: "error", mode: "live"; the upstream status and the technical reason travel in the response_status and reason fields rather than in the caller-facing message. A caller can therefore never mistake invented data for a real answer — fake data only ever arrives when it was asked for. The workflow test failed_call_errors_instead_of_faking_data locks this in.

• An internal assistant over company data. Several teams want a chat assistant that can read orders, customers, and rep performance. Rather than giving the assistant a database connection, you register it as one agent with the read scopes it needs, and the audit trail shows exactly which records it touched.
• Onboarding a third-party or vendor agent. A vendor's agent needs two capabilities and nothing else. POST agents/register issues it a key scoped to orders:search and clients:get; anything else it tries is refused before a call is forwarded, and the refusal is logged.
• Letting Claude or Cursor into a real backend, safely. The MCP server exposes four generic governed tools instead of your data endpoints, so an MCP client discovers what it may do, calls through the same chokepoint, and reads back only its own audit rows.
• Fronting several backend workspaces at once. Sales data lives in one Xano workspace, support data in another. Each capability row points at its own workspace with its own credential, so a leaked key from one does not open the others — and consumers keep calling one gateway.

Start with your coding agent. Paste the prompt below into a local MCP-capable coding agent — Claude Code, Cursor, Windsurf, and others. It installs the Xano CLI, connects Xano, and imports this template.

Start building in Xano: Access the prompt at https://go.xano.co/start-xano-with-template-skill and run it here with governed-agent-data-gateway as your template.

The agent will walk you through the setup below.

1. Deploy backend/ to a workspace (or install with the Xano template skill, which merges it into your existing workspace).
2. Seed. Admin endpoints are gated by API_AUTH_SECRET when it is set, and answer anyone when it is not — so this call works either way (send the header if your install carries the sample value; omit it after a plain push). Seeding is idempotent; the first run returns two demo agent keys, shown once:

curl -X POST https://<instance>/api:xil-admin/seed -H "X-API-Key: CHANGE_ME-operator-secret"

3. Check health — this one is public. source_reachable: true means the loopback hop to the reference group works, and seeded: true means step 2 landed. Expect two entries in warnings at this stage — one per security switch, saying it is unset (after a plain push) or still on the public sample value:

curl https://<instance>/api:xil-admin/health

4. Ask something with the full-access key from step 2:

curl -X POST https://<instance>/api:xil-layer/ask \
  -H "X-Agent-Key: xil_…" -H "Content-Type: application/json" \
  -d '{"message":"Will the Nashua delivery get rained on in the next 3 days?"}'

5. Show a denial. Repeat step 4 with the read-only key and ask it to file a ticket. The assistant explains the block; GET audit shows outcome: denied.
6. Deploy the console. Build frontend/index.html with your instance URL and API group canonicals, upload it to Xano Static Hosting, then create a username/password account in it:

node scripts/build-static.mjs https://<instance>.xano.io
xano static_host build push <host-name> -d dist

[!IMPORTANT] A fresh install is wide open, and health will tell you so. The two security switches — API_AUTH_SECRET and XIL_SOURCE_KEY — are declared in backend/workspace/xil.xs with the public sample values CHANGE_ME-operator-secret and CHANGE_ME-source-key, so the wiring is demonstrated rather than merely described. Whether they reach your workspace depends on the install path: xano workspace push does not send environment variables unless you pass --env, so after a plain push both are unset — which is the most open state there is, because an unset API_AUTH_SECRET makes every anonymous caller an operator with *:*. An install that does carry them lands on the sample values, which are printed in this repo and therefore not secrets either.

GET /api:xil-admin/health is the source of truth for which state you are in: it returns demo_mode: true and a warnings array naming each switch that is unset or still on a sample value, and the console shows the same as an amber banner. warnings: [] is the finish line — see Going to production.

Environment variables are listed under Environment variables; none are required to boot, and two are required to be safe. Regenerate the publication bundle after backend edits with node scripts/build-multidoc.mjs.

xil-layer — caller identified by X-Agent-Key, or X-API-Key, or open when API_AUTH_SECRET is unset

xil-auth — local browser accounts; passwords are hashed by the xil_user auth table

xil-app — requires Authorization: Bearer <user-token>

xil-admin — seed and agents/register require X-API-Key when API_AUTH_SECRET is set

xil-source-reference (COPY-ME) — requires X-Xil-Source-Key when XIL_SOURCE_KEY is set

Capabilities seeded (name → transport): orders.search, clients.get, branches.list, reps.performance → the source reference group; weather.forecast → Open-Meteo; countries.lookup → CountriesNow; fx.latest → open.er-api; catalog.search → DummyJSON; tickets.create → JSONPlaceholder (POST, the only write). All five outside services are keyless.

Header names are matched case-insensitively. Xano re-cases inbound header names (X-API-Key arrives as X-Api-Key), so every header read goes through xil_header, which compares on the lower-cased name. Send whatever casing you like.

xil-gateway-mcp exposes four tools — xil_mcp_list_capabilities, xil_mcp_resolve_intent, xil_mcp_call_capability, xil_mcp_recent_audit — and nothing else. MCP clients never see the raw data tools; they get the governed generic surface, and every call lands in the same audit log as the console.

Pass agent_key as a tool argument. That is what decides the caller's scopes and whose audit rows come back. Per-tool Xano user auth can additionally be enabled in the dashboard (that setting is not expressible in XanoScript).

There are two ways to connect, and the console's Connect Claude page walks through both:

Both security switches are declared with public sample values so the mechanism is demonstrated and closing the door is an edit rather than a discovery — but depending on your install path they may not have reached your workspace at all (see the note in Quick start). GET /api:xil-admin/health tells you where you stand — warnings: [] means production-shaped. The console shows an amber banner and a health chip until then.

Who can read the audit log. Reading the record of calls is governed as tightly as making them:

• /api:xil-layer/audit and the MCP xil_mcp_recent_audit tool return only the calling key's own rows. The response carries scope: "self".
• A caller holding *:* — an admin agent, the X-API-Key operator, or anyone at all while API_AUTH_SECRET is unset — sees the whole log (scope: "all") and may filter by agent_name.
• /api:xil-layer/steps returns a turn only to the caller that created it, or to an operator.
• Console rows belong to a signed-in user and are read through /api:xil-app/audit, filtered on $auth.id.

This is also why step 1 matters: while API_AUTH_SECRET is unset, everyone is an operator, so everyone sees everything.

Not included, and worth adding for a real deployment: per-agent rate limiting, key expiry, and a retention/redaction policy for request_payload.

The repo contains two clearly separated concerns, and only the first belongs in your gateway workspace:

To point the layer at a real source instead of the loopback demo:

1. Copy these files into the source workspace, then replace the ref_* queries with your own data:
   • backend/api/xil_source_reference/**
   • backend/table/ref_*.xs
   • backend/function/xil_ref_check_source_key.xs
2. In the source workspace, set XIL_SOURCE_KEY to a shared secret. Its endpoints then require header X-Xil-Source-Key.
3. In the layer workspace, set the same XIL_SOURCE_KEY, and set XIL_SOURCE_BASE_URL to the source instance origin.
4. GET health should report source_reachable: true against the new base URL. Nothing else changes: the proxy, scopes, and audit are identical in loopback and production.

Fanning out to several source workspaces

Step 3 wires up one source. The registry is built to address many, and each one gets its own credential — a leaked key from one workspace must not open the others. Three columns on xil_capability decide where a row lands:

So a two-source install looks like this:

Each source workspace sets its own XIL_SOURCE_KEY to the value the layer holds for it. xil_source_key resolves the reference at call time and xil_proxy_request sends it as X-Xil-Source-Key.

Verify a reference actually resolves before you trust it. GET /api:xil-admin/health returns source_credentials, one entry per distinct credential_ref in the registry, with an enforced flag — names only, never values. An enforced: false on a named reference means that workspace is being called with no credential at all, and health raises a warning for it:

"source_credentials": [
  { "name": "XIL_KEY_SALES",   "enforced": true  },
  { "name": "XIL_KEY_SUPPORT", "enforced": false }
]

Eight workflow tests ship with the template. All of them are credential-free and LLM-free, so they run in a fresh workspace with nothing configured:

xano workflow_test run_all -w <workspace_id>

Xano plans cap how many workflow tests a workspace can store. If a push fails with Your plan only supports N workflow tests, that is the cap, not the code — push a subset of backend/workflow_test/ (each file is one self-contained test), run it, then swap in the rest. This is how the suite was verified during the build: two passes of four against byte-identical backend code.

Data-and-setup flows, against the seed data the repo ships:

• seeded_source_data_answers_for_real — seeds the workspace, then reads the data back over real HTTP through the source contract with the shared source key, asserting the actual seeded counts. No mocks.
• health_reports_the_layer_is_seeded_and_wired — seeds, then asserts health reports the registry populated, the demo data loaded, the loopback hop answering, and a warning that the shipped sample secrets are still in place.

Governance flows:

• governed_call_is_forwarded_and_audited — an agent with orders:* calls orders.search with force_mock; expects mode: mock, data present, and an audit row of outcome: mock.
• scope_denied_call_is_logged_not_forwarded — an agent without tickets:create calls it; expects a plain refusal in __error, the missing scope in reason, mode: denied, and an audit row with outcome: denied and no upstream status.
• unknown_capability_is_refused_and_audited — a caller holding *:* asks for a capability that is not in the registry; expects a refusal and an audit row of outcome: error, proving the registry is the allow-list rather than the scope list.
• intent_resolves_to_a_capability_without_a_model — free text resolves to orders.search and weather.forecast by keyword rules, nonsense resolves to nothing rather than a guess, and a read-only agent is told it lacks the write scope before any call is made.
• agent_key_identifies_its_caller_and_can_be_revoked — issues a key, confirms it identifies its agent with exactly the scopes granted and nothing more, that the raw key is not recoverable from what was stored, then revokes it and confirms it stops working.
• failed_call_errors_instead_of_faking_data — a capability pointed at an unroutable host; expects __error, data: null, mode: live, and an audit row of outcome: error. This is the guard that a broken upstream is never quietly answered with canned data.

What is not covered automatically. The router agent itself (ai.agent.run on xano-free) is exercised by hand against a live workspace, not in the suite — a model's wording is not a stable assertion. The five keyless public APIs are likewise reached by hand and in the console; the suite deliberately does not depend on the open internet. Everything the tests do assert runs unattended, with no credentials.

Declared in backend/workspace/xil.xs and editable in the dashboard under Workspace settings → Environment Variables.

Values in the table below are what backend/workspace/xil.xs declares. A plain xano workspace push does not send environment variables (that needs --env), so after one both switches are unset until you set them in the dashboard — which is also why a push can never overwrite values you already have.

The router agent runs on xano-free, so no model key is needed. To use another provider, edit backend/ai/agent/xil_router.xs: set type to openai, anthropic, or google-genai and add api_key: $env.<YOUR_KEY>.

• API group canonicals are unique per Xano instance, not per workspace. The template ships them blank so Xano assigns a fresh one per install; read the real ones in the dashboard and use them in the frontend build and in any capability target_canonical.
• The credential boundary is described, not demonstrated, in the shipped template. The reference group lives in the same workspace, so the loopback hop is real HTTP but not a real trust boundary. Connecting your own source workspaces is the production shape.
• credential_ref is resolved dynamically ($env[<name>]). The default XIL_SOURCE_KEY is read statically and is always correct; confirm any named reference resolves via source_credentials in GET health before relying on it.
• Tools run inside ai.agent.run lose the endpoint's input context, so the router passes turn_id into every tool call. The fallback in xil_current_turn is used only when exactly one request is running; it never guesses between concurrent users.
• This is a tested starting point, not a compliance product. It gives you one enforcement point and a complete record of calls; retention, redaction, rate limiting, key expiry, and any formal certification are yours to add.