--- title: "Execute MCP query (read-only)" method: POST path: "/mcp/resources/query" tags: ["MCP Connectors"] --- # Execute MCP query (read-only) `POST /mcp/resources/query` ## Request - Base URL: `https://agent.getaxonflow.com` - URL: `https://agent.getaxonflow.com/mcp/resources/query` - Auth: none declared. Required headers: `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) Execute a read-only query via an MCP connector. This follows the MCP Resource pattern for data retrieval. For write operations, use `/mcp/tools/execute`. ## Audit Logging All MCP queries are automatically logged to the `mcp_query_audits` table with: - **Request phase**: SQLi detection results, PII blocking decisions - **Response phase**: PII redaction details, redacted field paths - **Exfiltration checks**: Row counts, volume limit violations - **Result**: Success/failure, error messages, duration Each audit entry includes `audit_id` for correlation with SDK `PolicyInfo`. Statement content is stored as SHA256 hash for privacy. ## Headers - `X-Axonflow-Approval-Id` string, uuid - `Authorization` string, required ## Request body - MCPQueryRequest - `approval_id` string, uuid: The approval a retry spends (#4370), for a client that cannot set the `X-Axonflow-Approval-Id` header (see that parameter). Never part of what the approval binds. - `client_id` string, required - `license_key` string: Can also be provided in X-License-Key header - `user_token` string - `connector` string, required: Connector name - `operation` string: Operation name (for API connectors like Amadeus) - `statement` string: SQL/CQL statement (for database connectors) - `parameters` object: Query parameters - `limit` integer: Maximum rows to return - `timeout` string: Timeout duration (e.g., "10s") ## Response `200` Query executed successfully - MCPQueryResponse - `success` boolean - `connector` string - `data` object[]: Query results - `row_count` integer - `duration_ms` integer - `redacted` boolean: Whether any fields in the response were redacted by policy enforcement - `redacted_fields` string[]: JSON paths of fields that were redacted (e.g., "data.rows[0].ssn") - `policy_info` PolicyInfo: Policy evaluation information included in MCP responses - `policies_evaluated` integer: Number of policies evaluated during request/response processing - `blocked` boolean: Whether the request was blocked by policy - `block_reason` string: Reason if the request was blocked - `redactions_applied` integer: Number of field redactions applied to the response - `processing_time_ms` integer: Time spent on policy evaluation in milliseconds - `matched_policies` PolicyMatchInfo[]: Policies that matched during evaluation - `policy_id` string: Unique policy identifier - `policy_name` string: Human-readable policy name - `category` string: Policy category (e.g., "pii-us", "security-sqli") - `severity` string: Match severity (low, medium, high, critical) - `action` string: Action taken (block, redact, warn, log) - `exfiltration_check` ExfiltrationCheckInfo: Information about exfiltration limit checks (v3.2.0+) - `rows_returned` integer: Number of rows in the response - `row_limit` integer: Configured row limit (MCP_MAX_ROWS_PER_QUERY) - `bytes_returned` integer: Response size in bytes - `byte_limit` integer: Configured byte limit (MCP_MAX_BYTES_PER_QUERY) - `within_limits` boolean: True when the response stayed within every configured limit - `engine` 'anchored': Which policy engine authored this verdict: the ADR-065 decision plane, the only author on this route (PRD v11 §1.1). It rides this body and the 403 envelope of a refusal by the same pass. Omitted on a refusal no engine decided - an authentication failure, or a request refused before the policy pass ran. - `subject_type` string: The type of principal the verdict was decided for (PRD v11 §1.6): `User` for a verified user token, `Client` when the request presented no user identity and its client credential is the principal. Omitted wherever `engine` is. - `policy_bundle` string: The digest of the policy set that decided: the system corpus's restriction for this route and the organization root - the organization's active typed document composed with the deployment's baseline permission pack, or, while it has published nothing, the implicit bundle of that pack and the organization template. A rollback reinstates an earlier digest. Omitted wherever `engine` is. - `policy_packs` string[]: The add-on policy packs (PRD v11 §1.9) whose controls composed into `policy_bundle` on the response pass, each as `@`, sorted. Omitted when the deployment installs no pack or none binds on this route. - `legacy_validators` object[]: A checksum validator that acted BEFORE the anchored engine decided (#4122): under an organization's recorded `pii=block` or `pii=redact` detection override, the Indonesia or India validator blocked the request or masked the response ahead of the decision plane. Omitted when none did, which is every request without such an override. - `validator` 'indonesia_pii' | 'india_pii', required - `action` 'blocked' | 'masked', required ## Other responses - `400`: Invalid request body or parameters - `401`: Missing or invalid authentication on an MCP REST route. FOUR distinct causes; the status code is the same for all four, and the audit row is what distinguishes the last two. 1. **Credentials.** No usable Basic auth / license credential. 2. **A tenant the credential may not act for.** 3. **`user_token_rejected`** -- a `user_token` WAS supplied in the request body and failed to validate: malformed, expired, signed with the wrong algorithm, carrying a bad signature, or revoked by `jti`. **This is new behaviour on these four routes.** Previously ANY user-token failure in enterprise mode was answered by synthesizing a service identity and serving the request, so revocation and expiry had no effect here; a presented token that fails to validate is now a refused access attempt, audited and returned as `401`. This is not opt-in and no flag restores the old behaviour. 4. **`user_token_required`** (#3476) -- NO `user_token` was supplied and the caller's organisation requires one. **Off by default**; this cause cannot occur unless an operator has set `organizations.require_user_token` for that organisation, or the deployment-wide `AXONFLOW_REQUIRE_USER_TOKEN` default. With the posture off, a token-less enterprise caller is still served under a synthetic service identity, which is the correct answer for an infrastructure gateway that has no end-user token to forward. Causes 3 and 4 are recorded as reserved identifiers in the audit row's policy ids and MUST NOT be collapsed: they have opposite operator remedies (repair the caller's token, versus provision one at all). Query them with JSONB containment against `policy_details->'policy_ids'`, never with `LIKE` -- `_` is a single-character wildcard, so a `%user_token_required%` pattern also matches unrelated prose in the same row. These routes read the per-user token from the `user_token` field of the request body. They do not read the `X-User-Token` header; that header belongs to the MCP-server JSON-RPC envelope. Handler-written 401s use the `{success, error}` envelope; 401s written by the auth middleware use the `{"error": {"code", "message"}}` envelope (JSONError). - `403`: Access denied. Causes on these routes: - **Tenant mismatch**, or a connector this tenant may not access. - **A policy refusal**: `error` is `Request blocked: `, the reason code first. - **A call held for a person's approval** (#4370, Enterprise): `error` is `Request blocked: approval_pending: ...` and `pending_approval` names the approval the retry spends (see the `X-Axonflow-Approval-Id` parameter). Nothing ran. `segment_resolution_failed` is no longer a cause (it was one from #3447). No segment gate stands on these routes any more: the anchored engine reads no segments, as on decide. - `404`: Connector not found - `500`: Internal server error --- [API](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/revisions/34d30fcb7fa1?raw)