Connect your
MCP client.

One governance service

aaesmcp is an adapter that lets an MCP client call your AAES service (the daemon). AAES Govern keeps the policy, registered capabilities, and application credentials. The adapter forwards calls using a bearer token issued by your deployment operator.

The credential resolves the tenant. Callers do not supply a tenant ID. On brokered paths, AAES Govern uses the configured application credential without intentionally handing it to the model. Validate that downstream results, errors, logs, and client behavior do not expose credentials; this is not a guarantee against leakage through those channels.

The aaesmcp binary ships in the evaluation or deployment package. Remaining protocol notes ship with that package.

Authenticate with a token file

For the stdio process, provide the operator-issued bearer token in a local file with permissions 0600 or 0400. The token is never a flag and is never printed. The -token-file flag accepts the file path, not the token itself.

chmod 0600 /path/to/aaes-token

Replace /path/to/aaes-token with the file your operator gave you. Keep the token out of prompts and client configuration JSON. Only its file path belongs in the launch configuration.

Connect over stdio

After you receive the package, launch the facade against your daemon. Packaged Compose uses TLS by default; configure the facade's system trust for the separately authenticated deployment certificate and use its HTTPS endpoint. The loopback HTTP examples below assume a dedicated test daemon started with explicit -allow-insecure-http opt-in. Point the command at the binary on your host:

/path/to/aaesmcp -daemon http://127.0.0.1:8090 -token-file /path/to/aaes-token

For an MCP client that uses a mcpServers configuration object:

{
  "mcpServers": {
    "aaes": {
      "command": "/path/to/aaesmcp",
      "args": [
        "-daemon",
        "http://127.0.0.1:8090",
        "-token-file",
        "/path/to/aaes-token"
      ]
    }
  }
}

127.0.0.1:8090 is the default listener address; the URL scheme follows the deployment's TLS configuration. Match -daemon to your deployment's platformd -listen address.

Streamable HTTP: POST only

Add a listener to expose the MCP endpoint locally:

/path/to/aaesmcp \
  -daemon http://127.0.0.1:8090 \
  -token-file /path/to/aaes-token \
  -listen 127.0.0.1:8765

Configure the client to send MCP requests to http://127.0.0.1:8765/mcp using POST.

tools/call over HTTP requires Authorization: Bearer with an operator-issued token. The process -token-file authenticates the stdio process to the daemon; it is not a fallback for HTTP.

Use a client that can operate with POST-only MCP requests, or use stdio.

Tool discovery

The facade lists these eight built-in tools in the following order, then the capabilities this caller may use.

The catalogue lists capabilities a caller may request access to. The capabilities list shows what that caller already has permission to use.

my_surfaces currently refuses. The daemon has no GET /v1/surfaces route, so the tool reports that fact rather than returning an empty list.

approval_status maps to the access-request read operation and expects an access-request identifier; it is not a general /v1/approvals/{id} lookup. The eight built-in tools do not include manager-card operations; agent managers read their inbox through the HTTP API or SDK.

Resources

Resources expose information available to the authenticated caller. The bearer token identifies the caller; resource URIs do not select a tenant or actor.

• resources/list lists aaes://entitlements and aaes://catalogue, using AAES Govern's capability and catalogue responses.
• resources/templates/list lists aaes://task/{task_id} and aaes://receipts/{receipt_id}. These read the named task or receipt and return an explicit refusal if the identifier is absent.
• The same template list includes aaes://policies/{capability_id}. It returns the policy's own fields from the catalogue only when that capability is requestable by this caller. Otherwise, it returns AAES Govern's refusal reason.
• resources/subscribe is refused explicitly. AAES Govern has no change feed, so the adapter cannot send change notifications.

The facade also serves two prompts, justify_access_request and explain_refusal. Each is grounded in the daemon's own answers at prompts/get time; when the daemon cannot be read, the prompt says so and instructs the model not to invent a justification.

Verify exported records offline

receipt_verify_pointer returns the command to run locally. Use the public aaesverify verifier against an export and public key from your evaluation install.

aaesverify --export <export.jsonl> --pubkey <key.pub>

This audit operation needs no running service. See the CLI reference for the offline audit commands.

Follow the daemon contract

The facade forwards to the HTTP API. Daemon refusals are JSON with a reason, plus a remedy when the daemon can name the smallest change that would satisfy the refusal.

The daemon contract is the public OpenAPI 3.1 schema. The operator console is served by the AAES Govern process on a separate listener and is not part of that contract.

A local check uses official Python MCP SDK 1.28.1 over stdio and stateless HTTP; other clients, SSE, sessions, and OAuth are not implied.

Back to developer documentation · Request an evaluation