XAA Debugger (CLI)

mcpjam xaa run drives a complete Cross-App Access flow, the Identity Assertion Authorization Grant (ID-JAG, an active IETF Internet-Draft), against your authorization server and MCP server. MCPJam plays the enterprise identity provider (it mints and signs the ID-JAG) and the client/agent (it redeems the ID-JAG and calls your MCP server with the resulting access token). Your authorization server and MCP server are the system under test.

mcpjam xaa run \
  --url http://localhost:8788/mcp \
  --issuer-base-url http://localhost:6274/api/mcp \
  --sub alice@example.com \
  --client-id my-registered-client

Recommended: use with Agent Skills

The easiest way to use the CLI is through the MCPJam skill, which gives your agent full context on every command and workflow.

npx skills add mcpjam/inspector --skill mcp-inspector

Once installed, your agent will know how and when to invoke mcpjam commands automatically, and how to read xaa run output conservatively (advertisement is evidence, redemption is the verdict; an issuer it can’t reach is your setup, not a server bug).

The three parties

Cross-App Access separates trust into three relationships that are easy to conflate. The CLI covers two of them and simulates the third:

Relationship	Who configures it	In this test
Client ↔ IdP	Enterprise SSO registration	Simulated: the CLI is the IdP, so this leg always succeeds
RAS ↔ IdP	Your authorization server trusts the IdP’s issuer + JWKS	You set this up once (see below)
Client ↔ RAS	OAuth client registration at your authorization server	Exercised per run via `--registration`

Before you run: make the issuer reachable

The CLI signs ID-JAGs with a local key pair (~/.mcpjam/xaa-idp-private.pem; override the directory with XAA_IDP_KEY_DIR). Your authorization server must be able to fetch the matching public key, so --issuer-base-url must be an origin that publishes that same key, not your real IdP’s URL. The local MCPJam inspector serves exactly this: it publishes the issuer metadata and JWKS from the same key directory at /api/mcp/xaa/.well-known/openid-configuration and /api/mcp/xaa/.well-known/jwks.json, no authentication required.

mcpjam inspector start    # serves the issuer at http://localhost:6274/api/mcp/xaa

Local authorization server: pass --issuer-base-url http://localhost:6274/api/mcp.
Cloud authorization server: it cannot reach your localhost. Expose the inspector origin through a tunnel and pass the public origin instead.

Then register the issuer in your authorization server: trust <issuer-base-url>/xaa as an ID-JAG issuer and point it at the JWKS URL above. The first flow step, verify_issuer_publication, fails fast if the issuer origin is unreachable or publishes a different key. Nothing is sent to your servers until it passes.

What a run checks

Each run walks the grant chain and reports every step:

verify_issuer_publication: the configured issuer publishes the CLI’s local signing key
discover_resource_metadata: protected-resource metadata (RFC 9728) names the authorization server protecting --url
discover_authz_metadata: authorization-server metadata (RFC 8414) provides the token endpoint and capability advertisements
mint_id_jag: the mock IdP exchanges the simulated user’s identity assertion for an ID-JAG (typ: oauth-id-jag+jwt, audience = your authorization server, resource = your MCP server)
redeem_id_jag: the ID-JAG is presented at your token endpoint via the JWT bearer grant (RFC 7523); your server validates it and issues its own access token
authenticated_mcp_request: an MCP initialize with the issued token, advertising the Enterprise-Managed Authorization extension

The result also records capability evidence separately from operational outcomes: whether your authorization server advertises the ID-JAG grant profile and the JWT bearer grant, which token-endpoint auth method was selected, and whether your MCP server advertises the enterprise-managed authorization extension back. Missing advertisements are reported as findings but never fail a flow that operationally succeeds: redemption is the verdict, advertisement is evidence. Capability evidence fields are three-valued: advertised, not_advertised (the metadata key was present but did not include the expected value), or unknown (the metadata key was absent entirely). unknown is weaker evidence than not_advertised. The two are not equivalent. The decoded ID-JAG claims and a local signature-verification verdict (idJag.verified) are included in the result so you can inspect exactly what your authorization server received. idJag.verified confirms the CLI’s own mint was well-formed and correctly signed; it is not evidence that your authorization server validated the assertion. The AS’s behavior is in the redemption block. Raw tokens, assertions, and secrets are always [REDACTED] in the output, including when a server reflects them back inside an error body.

Registration strategies

--registration selects how the CLI identifies itself to your authorization server, mirroring the client-registration models MCP clients use:

Strategy	Credentials needed	Posture notes
`preregistered` (default)	`--client-id` (+ optional `--client-secret`)	Matches the draft’s recommended deployment
`dcr`	none	A diagnostic: the CLI performs open RFC 7591 registration and supplies the IdP→RAS client mapping itself. Each run may leave a registration behind. RFC 7591 conformance findings are reported as warnings in `registration.warnings[]`
`cimd`	none	Public client by default. The run completes but is flagged: the draft recommends confidential clients
`cimd` + `--client-auth private-key-jwt`	none	Confidential CIMD: the CLI generates a local EC P-256 key, publishes it through the hosted reflector, and signs a `client_assertion`. The private key never leaves your machine

The registration.warnings[] array in the result uses these codes:

Code	Meaning	Weight
`public_client`	Client authenticates with no key or secret	Posture note: the draft recommends confidential clients, but this is not itself a vulnerability
`profile_metadata_not_echoed`	DCR response omitted `authorization_grant_profiles_supported`	Informational: RFC 7591 allows a server to ignore unknown metadata
`grant_types_not_echoed`	DCR response omitted `grant_types`	Informational: same rationale; redemption is the real signal
`missing_no_store`	DCR credential response lacked `Cache-Control: no-store`	Low compliance finding: RFC 7591 requires this header for credential-bearing responses

For confidential CIMD, the key is the identity: the reflector URL derived from the public key becomes the client_id. Deleting ~/.mcpjam/xaa-client-private.pem (or changing XAA_CLIENT_PRIVATE_KEY) mints a new identity, and any allowlisting on your authorization server must be updated.

Identity assertion formats

--assertion-format selects the identity rail the simulated enterprise uses:

oidc (default): the mock IdP mints an OIDC ID token as the token-exchange subject token.
saml: the mock IdP mints a SAML 2.0 assertion as the subject token, and the ID-JAG carries a saml-nameid sub_id claim so a SAML-federated authorization server can resolve the user.

The ID-JAG itself is always a JWT; the format flag changes the SSO leg and the subject identifier, not the grant. Either format composes with any registration strategy. Use --sub (and optionally --email) to control the simulated user, and --scopes for the permissions requested in both the ID-JAG and the token request.

Scenarios

First run against a local authorization server

mcpjam inspector start   # serves the issuer

mcpjam xaa run \
  --url http://localhost:8788/mcp \
  --issuer-base-url http://localhost:6274/api/mcp \
  --sub alice@example.com \
  --client-id my-registered-client \
  --scopes "mcp.access"

Confidential client without pre-registration

mcpjam xaa run \
  --url http://localhost:8788/mcp \
  --issuer-base-url http://localhost:6274/api/mcp \
  --sub alice@example.com \
  --registration cimd \
  --client-auth private-key-jwt

SAML-federated enterprise

mcpjam xaa run \
  --url http://localhost:8788/mcp \
  --issuer-base-url http://localhost:6274/api/mcp \
  --sub alice@example.com \
  --client-id my-registered-client \
  --assertion-format saml

CI

The JSON result goes to stdout; progress and advisory notes go to stderr. The exit code is 0 when the flow completes and 1 otherwise, so a run can gate a pipeline directly. Pass --quiet to suppress the advisory notes.

mcpjam xaa run \
  --url "$MCP_SERVER_URL" \
  --issuer-base-url "$ISSUER_ORIGIN" \
  --sub ci-probe@example.com \
  --client-id "$XAA_CLIENT_ID" \
  --quiet > xaa-result.json

Skipping discovery

--authz-server-issuer pins the authorization server and skips protected-resource discovery (useful while your MCP server’s RFC 9728 metadata is still in progress).
--token-endpoint pins the token endpoint and skips authorization-server discovery entirely. Not valid with dcr or cimd, which need the metadata document for the registration endpoint / CIMD advertisement.
--https-only rejects non-HTTPS and private targets; by default the CLI allows http://localhost for local development.

What this is not

These are targeted debugging checks for the current ID-JAG draft, not a conformance suite. The negative-test scorecard, sending deliberately broken ID-JAGs (bad signature, wrong audience, expired, and six more) and verifying your authorization server rejects each, lives in the inspector’s XAA Debugger, which also visualizes the flow and inspects the ID-JAG interactively before it is sent.

Guides

Reference

Recommended: use with Agent Skills

The three parties

Before you run: make the issuer reachable

What a run checks

Registration strategies

Identity assertion formats

Scenarios

First run against a local authorization server

Confidential client without pre-registration

SAML-federated enterprise

CI

Skipping discovery

What this is not

​Recommended: use with Agent Skills

​The three parties

​Before you run: make the issuer reachable

​What a run checks

​Registration strategies

​Identity assertion formats

​Scenarios

​First run against a local authorization server

​Confidential client without pre-registration

​SAML-federated enterprise

​CI

​Skipping discovery

​What this is not

​Related standards

Recommended: use with Agent Skills

The three parties

Before you run: make the issuer reachable

What a run checks

Registration strategies

Identity assertion formats

Scenarios

First run against a local authorization server

Confidential client without pre-registration

SAML-federated enterprise

CI

Skipping discovery

What this is not

Related standards