MCP server

Axowl speaks Model Context Protocol over Streamable HTTP at https://testapi.axowl.com/mcp. Point your own agent runtime at it and the agent acts under its badge — Axowl issues and enforces the authority, your runtime does the work.

This is the primary way to run an agent. The Axowl console harness is the fallback for teams with no runtime of their own.

Connect

In the dashboard, open your app group’s Agents tab and press the plug icon on the agent you want to run. Axowl issues a credential bound to that agent’s badge — expiring when the agent does — and hands you the exact command:

claude mcp add --transport http axowl https://testapi.axowl.com/mcp --header "Authorization: Bearer ah_live_..."

The credential is shown once and cannot be retrieved afterwards; issue a new one if you lose it.

To issue it yourself instead, POST /api/org/{slug}/settings/keys/api-keys with connectedIdId set to the agent’s badge. Either way it must be bound to an agent badge — a key with no connectedId, a human badge, or a badge that is suspended, revoked, or past its TTL is refused with a sentence explaining which.

If your client speaks OAuth — claude mcp add --transport http axowl https://testapi.axowl.com/mcp with no header — it discovers the authorization server, registers itself, and opens a browser. You sign in to Axowl, pick which agent it may act as, and approve. The token it receives names that one agent and names you as the delegating person.

This is the better path when a person is present, because the delegating person is whoever actually signed in, rather than whoever happened to issue a key months ago.

Under the hood: RFC 9728 protected-resource metadata, RFC 8414 server metadata, RFC 7591 dynamic client registration, authorization code with PKCE (S256 required), and rotating refresh tokens. Access tokens last an hour.

An agent that is suspended, revoked, or past its TTL stops working immediately — the badge is re-checked on every call, not at token issuance. Revoking does not wait for a token to expire.

Authority: the AND rule

An agent’s authority is what the agent holds ∩ what the person who delegated it holds.

The delegating person is whoever signed in (OAuth) or whoever issued the API key. This is not a formality — a request with no delegating person is refused outright, because an agent cannot act on nobody’s behalf. If you see every tool refusing, that is the reason, and axowl_whoami says so directly.

The consequence worth internalising: widening the agent alone will not lift a refusal that names the delegating user. A person cannot hand a machine authority they do not have themselves.

What you get: materials, not screens

Axowl does not build your application. It hands the agent the materials already attached to the app group and enforces what it may do with them:

app group ─┬─ connected repository (code) ──> read it, propose a pull request
           └─ attached database (data)    ──> read the schema, run SELECTs

Connecting the repository and the database is a person’s job — a prerequisite to hiring, not something the agent does. The agent gets read access to both, and the only way it changes code is a pull request.

Tools

Tool	What it does	Gate
`axowl_context`	App group, connected repo, attached DB, and what this agent may do	none
`axowl_whoami`	Badge, agent, app group, TTL, and who delegated it	none
`axowl_list_permissions`	Every concrete scope on the badge	none
`axowl_check_permission`	Ask about one scope before attempting it	none
`axowl_repo_list_files`	Paths in the connected repository’s default branch	`org.git_repository.read`
`axowl_repo_read_file`	Read one file from that branch	`org.git_repository.read`
`axowl_db_schema`	Tables and columns of the attached database	`org.data_source.read`
`axowl_db_query`	Run a SELECT and get rows back	`org.data_source.read`
`axowl_propose_code_change`	Open a pull request with whole-file changes	`org.git_repository.propose_change`

Start with axowl_context. It tells you what is connected and which of the above will actually work, so you find out before you try rather than after.

The database is read-only here

axowl_db_query runs SELECT and nothing else — that is the definition of the call, not a convention layered on top. Writes go through a separate path that passes an approval gate.

A failing query returns the database’s own error message, so your model can correct the statement and try again.

Code changes are pull requests, never pushes

axowl_propose_code_change takes whole files, not patches, and opens a pull request against the repository connected to this agent’s client. There is no direct-push path: merging is the human step. Three things are checked before anything is written — the badge’s authority, the paths (CI configuration and secrets are off limits, because an agent that can edit the pipeline can deploy itself), and the size (20 files, 512KB per pull request). Each rejection is reported individually.

Everything lands where a human can see it

Each write is recorded as a turn in a console thread named after the agent, so “what has this agent done” stays one screen. Refusals are sealed as agent.action_denied audit events; a pull request is sealed as agent.code_proposed.

Refusals are answers, errors are errors

The two are deliberately different:

No credential at all is a protocol problem. /mcp answers 401 with a WWW-Authenticate: Bearer resource_metadata="…" header, which is what lets a client discover the authorization server and start signing in.
A credential that lacks authority is a modelling problem. The tool returns 200 and the reason as its result — boards — denied (delegating user lacks org.record_schema.read). Your model reads that, understands what it lacks, and can ask a human to fix it. This is the same contract the Axowl console harness uses: a denial goes back to the model, never silently swallowed.

What is not here yet

No database writes. Reading is open; changing rows goes through an approval path that MCP does not expose.
One repository per agent. The agent reads the repository connected to the client it owns. If a client has none connected, axowl_context says so.

See also Agents and Roles & permissions.