Connect an AI agent

Airbrx exposes its admin surface over MCP, so an AI client can observe your cache, propose a rule, preview what that change would replace, write it, and check whether the hit rate moved. This page is the practical setup. For the model — and the boundary — read The AI control loop first.

Connect an interactive client

Point your MCP client at https://mcp.airbrx.ai/mcp. There is nothing to install and no API key to paste.

The client discovers that authentication is required, is pointed at the Airbrx API as the authorization server, registers itself, and opens a browser for you to log in and approve the connection. That is the only manual step. What the connection is backed by is a scoped personal access token minted at consent time; your client never handles its raw secret.

Once connected, ask the agent to run whoami as a first move. It reports your identity, your role on each tenant, and — importantly — your effective reach: the intersection of what your membership says and what the token's scopes allow. If it reports zero write paths, every write tool will fail with a permission error, and it is better to learn that before the agent has planned three steps around one.

Connect a headless client

For CI, a service account, or anything without a browser, create a personal access token and present it as the bearer token. The MCP server recognizes a raw PAT and exchanges it for a short-lived JWT on your behalf, caching the result — so a warm client exchanges roughly once an hour, not once per call. The raw token is never logged.

Scope the token to the tenant and the operations the job actually needs. A read-only analysis agent should hold a token with no write paths at all; that makes the read-only guarantee structural rather than a matter of prompting.

What the agent can do

Every tool is annotated as read-only or destructive, so a well-behaved client can prompt you for confirmation on the ones that matter instead of guessing. Seven tools write; six of those are marked destructive. Nothing reaches outside the Airbrx API.

Two guided workflows

Two multi-step routines are published as prompts — in most clients they appear as slash commands you pick deliberately. An agent will not start one on its own mid-conversation.

• Cache triage — why the hit rate moved. It walks from the monthly summary to the specific day the number changed, then works through the separable causes (rules changed, a rule that matches but never hits, a cache flush, a TTL shorter than the query's cadence, a shift in traffic mix), evidencing each one with a tool. It ends at a previewed proposal. It never writes.
• Access review — sweeps every grant scope and your tokens, then flags grants that never expire, delegation rights that look unwarranted, wildcard tokens, and orphaned child grants. It revokes nothing without asking you per item, and it tells you that revoking a delegating grant cascades to its children before offering you the choice.

Both open by checking who you are, so a step you lack the role for is announced up front rather than attempted and failed at the end. A guest can run the whole of cache triage and be told, at the start, who needs to land the change.

The one thing to insist on

Writing rules replaces the entire rule set. A candidate composed from partial knowledge silently deletes every rule it omits, and the write succeeds either way. This is the sharpest edge on the surface and it is worth a standing instruction to your agent:

Before any rule write, run the preview tool and show me the removal list. Do not write if anything is removed that I did not ask you to remove.

The preview reads your stored rules, diffs the candidate against them, and reports what would be removed and whether the change is destructive — without writing anything. But it is advisory: nothing in the server forces an agent to run it first. Treat an unpreviewed rule write the way you would treat an unreviewed migration.

The same holds for invalidation. Flushing a tenant's cache sends its entire read load back to your warehouse at once, which is a cost event and possibly a capacity one. The preview tool estimates that blast radius — the rules affected, the active markers, and the last week of traffic against those rules. Ask for it before approving a flush.

Permissions and audit are not special-cased

The MCP server verifies nothing and signs nothing. It attaches your token, forwards to the API, and returns the answer. Every authorization decision is made by the API using the same four-axis scope model as any other client, and every action lands in the same audit trail. An agent is not a distinct class of caller, which means you do not need a separate mental model for what one can do — the answer is exactly what its token allows.

Troubleshooting

• A tool the docs mention is missing. Almost always a stale client. MCP clients read the tool list once when they connect and cache it for the life of the connection, so a deployment that adds tools needs a reconnect to be seen. Disconnect and reconnect before assuming anything is wrong.
• Everything suddenly returns an auth challenge. Your token expired. Airbrx returns this as a transport-level challenge rather than a failed tool result, precisely so your client re-authenticates instead of reporting a broken tool. Log in again.
• Reads work, writes return 403. Your token has no write paths. Check whoami's reach, then re-scope the token.

Where to go next

• The AI control loop — the model, and why this is a control plane rather than a data path.
• Scope a token — the four axes, with worked examples.
• Handle rule issues — reading the analyzer warnings an agent will surface.