MCP-AQL Specification

Version: 1.0.0-draft Status: Draft Last Updated: 2026-04-15

Abstract

MCP-AQL (Model Context Protocol - Advanced Agent API Adapter Query Language) is a protocol specification that consolidates multiple MCP tools into a small number of semantic endpoints, providing significant token reduction while enabling runtime operation discovery through introspection. The standard CRUDE profile is one recommended semantic-endpoint pattern, but adapters MAY also define alternate semantic endpoint families that better match the target domain.

Status of This Document

This is the normative MCP-AQL specification. All conformance requirements (MUST, SHOULD, MAY) in this document are authoritative.

Other documents in the docs/ directory are informative and provide additional context, examples, and implementation guidance. In case of conflict between this specification and informative documents, this specification takes precedence.

This is a draft specification subject to change. Feedback is welcome via the specification repository.

This draft is intended for preliminary public launch and ecosystem experimentation. It is not yet a final certification baseline.

1. Introduction

1.1 Purpose

MCP-AQL addresses the token efficiency challenge in LLM-MCP interactions. Traditional MCP implementations expose discrete tools, each requiring schema definition in the model's context. With many tools, this can consume significant tokens before any work begins.

MCP-AQL consolidates operations into a small number of semantic endpoints, reducing token overhead by approximately 85-96% while maintaining full functionality.

1.2 Goals

1. Token Efficiency - Minimize context consumed by tool definitions
2. Semantic Clarity - Group operations by their effect on system state
3. Runtime Discovery - Enable operation discovery via introspection
4. Flexibility - Support multiple endpoint modes for different use cases
5. Genericity - Work with any domain, any backend, any operation set

1.3 Scope

This specification defines:

• Standard semantic operation categories
• Endpoint family patterns, including the standard CRUDE profile
• Request and response formats
• The introspection system for operation discovery
• Operation classification guidelines
• Conformance requirements

This specification does NOT define:

• Specific operations (adapters define their own)
• Domain-specific concepts (adapters define their own)
• Implementation architecture details
• Transport-layer concerns (handled by MCP)

1.4 Relationship to Adapters

MCP-AQL is a protocol layer, not an application. Adapters implement MCP-AQL to expose their domain-specific operations through semantic endpoints or a single unified endpoint. Each adapter:

• Defines its own operations
• Defines its own parameters
• Classifies operations into standard semantic categories
• Maps operations to exposed endpoint families
• Exposes operations via introspection

2. Terminology

2.1 Key Terms

CRUDE Pattern : The five-endpoint pattern: Create, Read, Update, Delete, Execute

Semantic Category : One of the standard operation-effect categories: CREATE, READ, UPDATE, DELETE, EXECUTE

Operation : A specific action that an adapter provides (e.g., create_user, run_report, search_documents)

Endpoint Family : A named exposed endpoint or tool grouping that contains one or more operations

Adapter : An MCP server that implements MCP-AQL to expose domain-specific operations

Introspection : The ability to query available operations and types at runtime

Resource : Any entity managed by an adapter (documents, users, configurations, workflows, etc.)

2.2 Requirement Levels

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2.3 Session Lifecycle

2.3.1 Definition

An MCP-AQL session is the lifetime of a single MCP connection, beginning when the MCP initialize handshake completes successfully and ending when the connection terminates.

2.3.2 Session Boundaries

A session is strictly 1:1 with an MCP connection. If a transport disconnects and reconnects, the new connection is a new session — even if the same client reconnects immediately.

2.3.3 Session-Scoped State

The following are session-scoped and MUST NOT survive session termination:

• Confirmation tokens (default behavior per Section 5.4 of the Confirmation Token Specification; adapters MAY explicitly persist tokens across sessions)
• Cached introspection results
• In-progress EXECUTE operation context (pending state machine transitions)
• Warning deduplication state

Adapters MUST invalidate all session-scoped state when a session ends, whether gracefully or abruptly. In-progress EXECUTE operations SHOULD transition to failed or cancelled as defined by the execution lifecycle (Section 8.4).

2.3.4 Cross-Session Persistence

The following MAY persist across sessions:

• Adapter configuration and operation schemas
• Stored resources and data managed by the adapter
• Audit logs and telemetry
• Completed execution results (terminal states)

2.3.5 Session Identification

Adapters MAY track sessions using:

• MCP connection identifier (if provided by the transport)
• Internally generated session ID
• Client-provided metadata (via _meta) as a labeling hint

Client-provided _meta values MUST be treated as labels for logging purposes only. Adapters MUST NOT use client-provided values as authoritative session identity for security decisions (e.g., token validation, access control).

Session identifiers SHOULD be included in audit logs and error responses for debugging.

Implementation Note: MCP does not define a standard session identifier field. Adapters that need session tracking SHOULD generate their own identifier when the initialize handshake completes and include it in the _protocol metadata returned by introspection.

3. Protocol Overview

3.1 Architecture

┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                           │
│                     (LLM / Agent)                           │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     MCP-AQL Layer                           │
│  ┌──────────────────────────────────────────────────────┐   │
│  │        Exposed Endpoint Families                     │   │
│  │  Semantic endpoint profile or unified endpoint       │   │
│  └──────────────────────────────────────────────────────┘   │
│                          │                                  │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Operation Router                        │   │
│  │   Routes operations to correct handlers              │   │
│  └──────────────────────────────────────────────────────┘   │
│                          │                                  │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Introspection System                    │   │
│  │   Provides runtime operation discovery               │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                    Domain Backend                           │
│         (Database, API, Service, File System, etc.)         │
└─────────────────────────────────────────────────────────────┘

3.2 Request Flow

1. Client sends request to MCP-AQL endpoint
2. Router extracts operation field
3. Router validates operation belongs to receiving endpoint
4. Parameters are extracted and validated
5. Handler executes operation
6. Response returned to client

3.3 Endpoint Modes

MCP-AQL supports two operational modes:

Semantic Endpoint Mode

The standard CRUDE profile:

mcp_aql_create   - CREATE operations
mcp_aql_read     - READ operations
mcp_aql_update   - UPDATE operations
mcp_aql_delete   - DELETE operations
mcp_aql_execute  - EXECUTE operations

An alternative semantic profile:

mcp_aql_discover  - Discovery and inspection operations
mcp_aql_query     - Retrieval and filtering operations
mcp_aql_manage    - Mutating and administrative operations
mcp_aql_operate   - Runtime and lifecycle operations

Other valid semantic endpoint families might be shaped around semantically explicit profiles such as database access (inspect, query, mutate, administer) or hardware integrations (discover, observe, control, maintain).

Single Mode (1 endpoint)

mcp_aql - All operations through unified entry point

Implementations MUST support at least one mode. Implementations SHOULD support both.

4. Request Format

4.1 Standard Request Structure

interface OperationInput {
  operation: string;              // REQUIRED: Operation to perform
  params?: Record<string, any>;   // OPTIONAL: Operation parameters
}

4.2 Parameter Resolution

Parameters MAY appear at multiple levels. Resolution follows this precedence:

1. params.<parameter_name>
2. Top-level <parameter_name>

4.3 Parameter Naming

All public-facing parameters MUST use snake_case naming (matching the pattern ^[a-z][a-z0-9_]*$) for consistency across adapters.

Terminology Note: The request field params (an object of key-value pairs) contains runtime parameter values. The introspection field parameters (an array of ParameterInfo entries) describes the accepted parameter definitions. The keys of params correspond to the name field of each entry in parameters.

4.4 Request Examples

Minimal Request:

{
  "operation": "list_users"
}

Request with Parameters:

{
  "operation": "create_document",
  "params": {
    "title": "Quarterly Report",
    "content": "...",
    "folder_id": "folder_123"
  }
}

Alternative Parameter Placement:

{
  "operation": "get_user",
  "user_id": "user_456"
}

Collection Querying Note: Collection-returning READ operations often combine field selection, filtering, sorting, and pagination. See the informative Collection Querying guide for the preferred cross-cutting request shape moving forward.

4.5 UPDATE Input Pattern

UPDATE operations MUST use a nested input object within params to contain all updateable fields. Identifier parameters (used to locate the resource) MUST remain at the params level.

Structure:

{
  "operation": "update_resource",
  "params": {
    "resource_id": "res_123",
    "input": {
      "title": "New Title",
      "metadata": {
        "priority": "high"
      }
    }
  }
}

4.5.1 Merge Semantics

When processing the input object, adapters MUST apply deep-merge semantics:

1. Top-level fields in input replace existing values entirely
2. Nested objects merge recursively (keys present in input are updated; keys absent from input are preserved)
3. Arrays replace entirely (no element-level merging)
4. Explicit null removes the field from the resource

Example — Deep Merge Behavior:

Given existing resource state:

{
  "title": "Old Title",
  "metadata": {
    "priority": "low",
    "tags": ["draft"],
    "author": "alice"
  }
}

And update request:

{
  "operation": "update_resource",
  "params": {
    "resource_id": "res_123",
    "input": {
      "title": "New Title",
      "metadata": {
        "priority": "high",
        "tags": ["published", "reviewed"]
      }
    }
  }
}

The resulting state MUST be:

{
  "title": "New Title",
  "metadata": {
    "priority": "high",
    "tags": ["published", "reviewed"],
    "author": "alice"
  }
}

• title: replaced (top-level field)
• metadata.priority: replaced (present in input)
• metadata.tags: replaced entirely (array)
• metadata.author: preserved (absent from input)

4.5.2 Field Removal

To remove a field, clients MUST set its value to null:

{
  "operation": "update_resource",
  "params": {
    "resource_id": "res_123",
    "input": {
      "metadata": {
        "deprecated_field": null
      }
    }
  }
}

4.5.3 Validation

Adapters MUST validate the input object:

1. The input field MUST be present for UPDATE operations; adapters MUST reject requests missing input with a VALIDATION_MISSING_PARAM error
2. The input field MUST be an object when present
3. Fields within input MUST be validated against the resource schema
4. Unknown fields within input SHOULD be rejected with a VALIDATION_UNKNOWN_FIELD error
5. Identifier parameters MUST NOT appear inside input

See ADR-002: GraphQL-Style Input Objects for design rationale.

4.6 Unknown Parameter Handling

Adapters MUST reject requests containing parameters not defined in the operation schema.

When an unknown parameter is detected, adapters MUST return a VALIDATION_UNKNOWN_PARAM error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_UNKNOWN_PARAM",
    "message": "Unknown parameter 'force_create' for operation 'create_user'",
    "details": {
      "operation": "create_user",
      "unknown_params": ["force_create", "admin_override"],
      "valid_params": ["user_name", "password", "email"]
    }
  }
}

This requirement:

• Prevents typos from silently failing
• Prevents LLM hallucination of non-existent parameters
• Provides actionable feedback for correction

4.6.1 Scope

Unknown parameter validation applies to:

• Parameters within the params object
• Top-level parameters (when parameter resolution is enabled per Section 4.2)

Unknown parameter validation does NOT apply to:

• Protocol-level fields (operation, params)
• Metadata fields prefixed with underscore (_meta, _request_id)

4.6.2 Strict Mode Configuration

Adapters MAY implement a strict_mode configuration option. When strict_mode is disabled (development environments only), adapters MAY log warnings for unknown parameters instead of rejecting the request.

When strict_mode is enabled or not configured, the default behavior MUST be rejection.

Implementation Note: The strict_mode setting is considered implementation-internal configuration and is not exposed via introspection. Clients SHOULD always assume strict validation is enabled and not rely on lenient behavior.

4.7 Data Types and Encoding

This section defines data encoding requirements for interoperability across adapters.

4.7.1 Character Encoding

All text MUST be encoded as UTF-8. Adapters MUST reject requests containing invalid UTF-8 sequences with a VALIDATION_INVALID_ENCODING error.

Invalid UTF-8 sequences include:

• Overlong encodings (e.g., using 2 bytes to encode a character that fits in 1)
• Invalid continuation bytes
• Truncated multi-byte sequences
• Surrogate code points (U+D800 to U+DFFF)

Adapters SHOULD reject strings containing null bytes (U+0000) unless explicitly documented as supported for the parameter, as null bytes can cause issues in many languages and databases.

4.7.2 Date and Time

Dates and timestamps MUST use ISO 8601 format:

• Date only: 2026-02-04
• Date-time (UTC): 2026-02-04T10:30:00Z
• Date-time with offset: 2026-02-04T10:30:00+05:30

Adapters SHOULD use UTC (Z suffix) for timestamps in responses. Adapters MUST document timezone handling for date-only values.

4.7.3 Numbers

Numeric values follow JSON number syntax (RFC 8259), which uses IEEE 754 double-precision floating-point:

• Safe integer range: ±(2^53 - 1), i.e., ±9,007,199,254,740,991
• Precision: Approximately 15-17 significant decimal digits

For values requiring higher precision (e.g., financial amounts, large identifiers), adapters SHOULD use string representation:

{
  "amount": "12345678901234567890",
  "amount_type": "bigint"
}

Note: The type indicator field name (e.g., amount_type) is adapter-specific. Adapters SHOULD document their conventions for distinguishing string-encoded numbers from regular strings.

Adapters MUST document when string representation is required for numeric parameters.

4.7.4 Binary Data

Binary data MUST be encoded as base64 (RFC 4648) with standard padding (= characters) and metadata:

{
  "file_content": "SGVsbG8gV29ybGQ=",
  "file_encoding": "base64",
  "file_mime_type": "text/plain"
}

Adapters MAY support alternative binary handling (e.g., URL references, multipart) but MUST document this behavior via introspection.

4.7.5 Payload Size Limits

Adapters MUST enforce payload size limits to prevent resource exhaustion:

Nesting depth counting: Depth counts the levels of nested objects or arrays. For example, {"a": {"b": {"c": {}}}} has a depth of 4. The root object counts as level 1.

When a limit is exceeded, adapters MUST return a VALIDATION_PAYLOAD_TOO_LARGE error with details indicating which limit was exceeded.

Adapters MUST document their configured limits via introspection or adapter documentation. Adapters SHOULD expose limits in protocol metadata (see Section 9.3.3) to enable client-side pre-validation:

{
  "_protocol": {
    "limits": {
      "max_request_size": 1048576,
      "max_response_size": 10485760,
      "max_string_length": 1048576,
      "max_array_elements": 10000,
      "max_nesting_depth": 32
    }
  }
}

4.7.6 Null Handling

JSON null represents the absence of a value:

• In requests: Omitting a field and explicitly setting it to null MAY have different semantics. See Section 4.5.2 for UPDATE operations where null removes fields.
• In responses: null indicates the field exists but has no value.

Adapters MUST document null semantics for parameters where the distinction matters.

5. Response Format

5.1 Discriminated Union

All operations return a discriminated union result:

type OperationResult = OperationSuccess | OperationFailure;

interface OperationSuccess {
  success: true;
  data: any;      // Operation-specific payload
}

interface OperationFailure {
  success: false;
  error: ErrorDetail;
}

interface ErrorDetail {
  code: string;     // Machine-readable error code (e.g., "VALIDATION_MISSING_PARAM")
  message: string;  // Human-readable error message
  details?: Record<string, unknown>;  // Optional contextual information
}

Note: See Structured Error Codes Specification for the complete error code taxonomy and usage guidelines.

5.2 Success Response

{
  "success": true,
  "data": {
    "id": "doc_789",
    "title": "Quarterly Report",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

5.3 Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_MISSING_PARAM",
    "message": "Missing required parameter 'title' for operation 'create_document'",
    "details": {
      "param_name": "title",
      "operation": "create_document"
    }
  }
}

6. Endpoint Families

6.1 Standard Semantic Categories

6.2 Operation Routing

Each operation MUST be assigned exactly one standard semantic category based on its characteristics. In semantic endpoint mode, each operation MUST also be routed to exactly one exposed endpoint family. Implementations MUST reject operations sent to incorrect endpoints in semantic endpoint mode.

See Protocol Overview for detailed endpoint definitions and classification guidelines.

7. Introspection

7.1 Purpose

Introspection enables clients to discover available operations without parsing tool schemas, providing:

• On-demand operation discovery
• Parameter documentation
• Type information
• Usage examples

7.2 The introspect Operation

Endpoint: READ

Every MCP-AQL adapter MUST implement the introspect operation.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Query type: "operations" or "types" | | name | string | No | Specific item name for details |

7.3 Query Types

List Operations:

{ "operation": "introspect", "params": { "query": "operations" } }

Operation Details:

{ "operation": "introspect", "params": { "query": "operations", "name": "create_document" } }

List Types:

{ "operation": "introspect", "params": { "query": "types" } }

Type Details:

{ "operation": "introspect", "params": { "query": "types", "name": "DocumentStatus" } }

See Introspection Specification for detailed response structures.

8. Operation Classification

8.1 Classification Guidelines

Adapters classify their operations into standard semantic categories based on characteristics:

CREATE - Operations that:

• Add new resources or state
• Do not remove or overwrite existing data
• Are non-destructive

READ - Operations that:

• Query or retrieve data
• Have no side effects on stored state
• Are safe to call repeatedly (idempotent)

UPDATE - Operations that:

• Modify existing resources
• Overwrite previous values
• Require the resource to exist

DELETE - Operations that:

• Remove resources permanently
• Are irreversible without backup
• May require confirmation

EXECUTE - Operations that:

• Manage runtime lifecycle (start, stop, monitor)
• Are non-idempotent (each call may create new state)
• May have external side effects

8.2 Classification Examples

8.3 Edge Cases

When classification is ambiguous:

• Prefer READ if operation has no side effects
• Prefer CREATE over UPDATE if resource may not exist
• Prefer EXECUTE for operations with external effects
• Document reasoning in adapter specification

8.4 Execution Lifecycle

EXECUTE operations that create or manage long-running processes SHOULD follow the standard execution lifecycle defined in this section.

8.4.1 Core States

8.4.2 State Transitions

                              ┌───────────┐
                              │ cancelled │
                              └───────────┘
                                    ▲
                    cancel          │           cancel
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
     ┌────────┴─┐             ┌─────┴────┐          ┌─────┴────┐
     │ pending  │───start────▶│ running  │◄──retry──│  failed  │
     └──────────┘             └────┬─────┘          └──────────┘
                                   │                      ▲
                                   │ success/error        │
                                   ▼                      │
                              ┌─────┴────┐                │
                              │          │────────────────┘
                              ▼          ▼
                         ┌────────┐  ┌────────┐
                         │completed│  │ failed │
                         └────────┘  └────────┘
                          (terminal)  (may retry)

Terminal States: completed, failed, and cancelled are terminal states. Once an execution reaches a terminal state, it MUST NOT transition to any other state except for the optional failed → running retry transition when supported.

Valid state transitions:

• pending → running (start)
• pending → cancelled (cancel before start)
• running → completed (successful completion)
• running → failed (error during execution)
• running → cancelled (user cancellation)
• failed → running (retry, if supported)

8.4.3 State Response Format

Operations that return execution state SHOULD include:

{
  "execution_id": "exec_123",
  "status": "running",
  "started_at": "2026-02-04T10:00:00Z",
  "progress": {
    "current": 45,
    "total": 100,
    "message": "Processing step 5 of 10"
  }
}

Required Fields: | Field | Type | Description | |-------|------|-------------| | execution_id | string | Unique identifier for the execution | | status | string | Current state (one of the core states) |

Optional Fields: | Field | Type | Description | |-------|------|-------------| | started_at | string (ISO 8601) | When execution started | | finished_at | string (ISO 8601) | When execution reached a terminal state | | progress | object | Progress information (see below) | | error | object | Error details if status is failed (see Error Response Format) |

Progress Object:

When progress is present, at least one of the following SHOULD be included:

Example — Completed Execution:

{
  "execution_id": "exec_123",
  "status": "completed",
  "started_at": "2026-02-04T10:00:00Z",
  "finished_at": "2026-02-04T10:05:32Z"
}

Example — Failed Execution:

{
  "execution_id": "exec_456",
  "status": "failed",
  "started_at": "2026-02-04T10:00:00Z",
  "finished_at": "2026-02-04T10:02:15Z",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Connection timeout while processing",
    "details": { "step": "data_fetch", "attempt": 3 }
  }
}

Example — Cancelled Execution:

{
  "execution_id": "exec_789",
  "status": "cancelled",
  "started_at": "2026-02-04T10:00:00Z",
  "finished_at": "2026-02-04T10:01:45Z",
  "progress": {
    "percentage": 35,
    "message": "Cancelled by user during data processing"
  }
}

8.4.4 Adapter Extensions

Adapters MAY define additional states beyond the core set (e.g., paused, queued, retrying). When extending the state machine:

1. Custom states MUST be documented via introspection
2. Custom states SHOULD map conceptually to core states for generic client compatibility
3. Adapters MUST support transitions to cancelled from any non-terminal state
4. Adapters SHOULD document which operations trigger each state transition

Example Extended State Mapping: | Adapter State | Maps To | Description | |---------------|---------|-------------| | queued | pending | Waiting in job queue | | paused | running | Temporarily suspended | | retrying | running | Automatic retry in progress |

8.4.5 Introspection Support

EXECUTE operations that manage lifecycle SHOULD expose their supported states via introspection. The lifecycle field in operation details indicates lifecycle support:

{
  "operation": {
    "name": "execute_job",
    "semantic_category": "EXECUTE",
    "endpoint": "operate",
    "lifecycle": {
      "states": ["pending", "queued", "running", "completed", "failed", "cancelled"],
      "supports_cancel": true,
      "supports_retry": false,
      "progress_reporting": true
    }
  }
}

See Introspection Specification for the complete schema.

8.5 Operation Naming Grammar

8.5.1 Canonical Verbs

Each endpoint has one or more canonical verbs that SHOULD be used for standard operations:

cancel covers both aborting a pending/queued operation and halting a currently running one. Adapters that need to distinguish these cases MAY use additional verbs (e.g., stop) alongside cancel.

Using canonical verbs improves cross-adapter consistency, enabling LLMs to predict operation names without requiring introspection for every adapter.

For developers familiar with REST conventions, the following mapping provides context:

8.5.2 Operation Name Format

Operation names MUST use snake_case naming (a lowercase letter followed by lowercase letters, digits, and underscores), matching the schema pattern ^[a-z][a-z0-9_]*$. Operations SHOULD follow the pattern: {verb}_{resource}

Examples:

• create_user (not add_user)
• get_document (not fetch_document)
• list_items (not find_items)
• update_profile (not edit_profile)
• delete_account (not remove_account)
• execute_workflow (not run_workflow)

Operations that act on the system as a whole (rather than a specific resource) MAY omit the resource suffix (e.g., introspect).

8.5.3 When to Use Non-Canonical Verbs

Non-canonical verbs MAY be used when:

1. The operation has domain-specific semantics (e.g., upload_file vs create_file when the operation involves binary transfer)
2. The canonical verb would be misleading (e.g., search implies query semantics that list does not)
3. Industry convention strongly favors a different verb (e.g., import/export)

When using non-canonical verbs, adapters SHOULD:

• Document the rationale in the operation description
• Note the canonical equivalent in the operation description (e.g., "Similar to create, but handles binary upload")

8.5.4 Reserved Operations

The following operation names are reserved for protocol use and MUST NOT be used by adapters for other purposes:

Adapters MUST NOT define custom operations with these names for other purposes. Future specification versions MAY reserve additional operation names.

8.6 Execution Safety Loop

The execution safety loop is an opt-in enforcement pattern that provides continuous safety evaluation of an agent's intended actions during execution. When active, it turns the execute lifecycle (Section 8.4) into a monitored enforcement boundary rather than a simple state tracker.

Terminology Note: The "execution safety loop" is distinct from the full agent lifecycle that a specific adapter may implement. The safety loop is a protocol-level monitoring pattern; agent lifecycle management (personas, elements, state) is an adapter concern.

Forward Reference: This section references the Autonomy Evaluator (Section 8.7) and Out-of-Band Verification (Section 8.8), which are defined as companion sections. The AutonomyDirective response type is formally defined in Section 8.7.1.

8.6.1 Opt-In Activation

The execution safety loop is an OPTIONAL feature. Adapters MAY support it, and clients MAY choose to enable it.

• When not enabled, the adapter operates normally without safety enforcement overhead
• Activation is explicit — via execute_agent to start a monitored execution, or via adapter configuration to enable safety-loop mode
• Adapters MUST document whether they support the execution safety loop via introspection

Adapters that support the execution safety loop SHOULD expose this capability in their introspection response:

{
  "capabilities": {
    "execution_safety_loop": "enforcing"
  }
}

Valid values for execution_safety_loop:

8.6.2 Enforcement Boundary Property

When the execution safety loop is active, it establishes a mandatory enforcement boundary: all intended actions MUST be reported before execution, and all reports MUST be evaluated before the agent proceeds.

The enforcement chain:

1. An agent starts via execute_agent, which requires explicit approval (one-time gate)
2. The agent is now running inside the execution safety loop
3. Every action the agent intends to take MUST be reported via record_execution_step with nextActionHint
4. Each report is evaluated by the adapter's safety pipeline (Gatekeeper, Autonomy Evaluator, Danger Zone — see Sections 8.7, 8.8)
5. The evaluation returns an AutonomyDirective (Section 8.7.1) indicating whether the agent may proceed
6. The loop continues until complete_execution or abort_execution

The initial execute_agent approval grants monitored trust, not blanket trust. The approval starts continuous per-action evaluation.

Between execute_agent approval and the first record_execution_step call, the agent MAY perform internal reasoning (planning, context gathering) but MUST NOT take any externally-visible action. The first action with external effects MUST be reported before execution.

The loop terminates via complete_execution (normal success) or abort_execution (abnormal termination, e.g., after a stop directive or user cancellation).

8.6.3 Mandatory Action Reporting

When the execution safety loop is active, agents MUST report all intended actions through record_execution_step with a nextActionHint describing the planned action. Actions taken without reporting are a protocol violation.

A reportable action is any operation that causes effects beyond the agent's internal reasoning:

• Tool calls to any MCP server (including other adapters)
• File system operations (read, write, delete)
• Shell command execution
• Network requests to external services
• Database queries or mutations
• State changes in any connected system

The record_execution_step operation accepts the following parameters:

The nextActionHint field MUST be a human-readable string describing the intended action with sufficient detail for safety evaluation. Examples:

• "calling write_file on project/config.json to update database URL"
• "executing shell command: npm install express"
• "sending message to #general channel via Slack MCP server"

8.6.4 Continuous Enforcement

Every record_execution_step call is an evaluation checkpoint. The response includes an AutonomyDirective (Section 8.7.1) that is authoritative:

• When continue is true, the agent MAY proceed with the reported action
• When continue is false, the agent MUST NOT proceed. The agent SHOULD report the pause to the user or upstream system
• When stopped is true, the agent has been hard-blocked (Section 8.8). The agent MUST cease all actions until unblocked via out-of-band verification

Implementations MUST NOT allow agents to proceed after a stop directive. Implementations SHOULD NOT allow agents to proceed after continue: false without human intervention.

In monitoring mode ("monitoring"), continue is always true and stopped MUST NOT be set to true. Monitoring mode is advisory only — it evaluates and logs but does not block. In logging mode ("logging"), no evaluation occurs and no directive fields are authoritative.

8.6.5 Non-Bypass Property

If an agent is executing through the execution safety loop, it MUST NOT perform actions outside the reported loop. This property is essential to the safety model:

• The agent MUST NOT call tools on other MCP servers without first reporting intent via record_execution_step
• The agent MUST NOT take file system or shell actions without reporting
• If the agent acts without reporting, it is a protocol violation

Implementation Note: This property is enforced cooperatively — the agent (typically an LLM following system prompt instructions) must be instructed to check in with the safety loop before every action. The protocol defines the contract; the client integration enforces it.

8.6.6 Scope of Monitoring

The execution safety loop monitors ALL intended actions, not only MCP-AQL operations on the same adapter. This includes:

• Tool calls to other MCP servers in the same client session
• Tool calls to non-MCP-AQL MCP servers
• Built-in client capabilities (file I/O, shell access, web requests)
• Any operation that produces effects beyond the agent's reasoning context

This broad scope is what makes the safety dongle deployment model possible: a standalone MCP-AQL server can function as a universal safety layer for all tool calls in a client session, regardless of which server handles the actual operation.

8.6.7 Disabling the Safety Loop

Clients or adapter configuration MAY disable the execution safety loop entirely. When disabled:

• The execution lifecycle operations (execute_agent, record_execution_step, complete_execution, abort_execution) are either unavailable or operate as no-op progress tracking without safety enforcement
• No AutonomyDirective evaluation occurs
• No action reporting is required

The adapter MUST clearly indicate via introspection whether safety enforcement is active or disabled:

{
  "capabilities": {
    "execution_safety_loop": "disabled"
  }
}

8.7 Autonomy Evaluation

When the execution safety loop is active, every record_execution_step call triggers an autonomy evaluation. This section defines the evaluation pipeline and the AutonomyDirective response contract.

8.7.1 The AutonomyDirective Contract

The AutonomyDirective is returned as part of the record_execution_step response. It is the authoritative signal for whether the agent may proceed.

interface AutonomyDirective {
  continue: boolean;              // Whether the agent may proceed
  factors: string[];              // Human-readable decision factors
  stopped?: boolean;              // True if hard-blocked (Section 8.8)
  reason?: string;                // Why paused or stopped
  stepsRemaining?: number;        // Steps before mandatory pause
  nextStepRisk?: SafetyTier;      // Risk tier of the evaluated action
  notifications?: AgentNotification[]; // Pending events (Section 8.7.3)
}

type SafetyTier = "advisory" | "confirm" | "verify" | "danger_zone";

Implementations MUST include continue and factors in every AutonomyDirective. All other fields are OPTIONAL except where specific sections impose MUST requirements (see Sections 8.8.1 and 8.8.2 for mandatory notifications in verify tier, danger_zone tier, and deny pattern scenarios).

8.7.2 Evaluation Pipeline

Implementations SHOULD evaluate actions through a multi-stage pipeline. The stages are evaluated in order; the first stage that triggers a pause or stop ends the evaluation:

Stage 1 — Step Limit Check:

Compares the current step count against a configurable maxAutonomousSteps threshold.

• When the step count exceeds the limit, the evaluator SHOULD return continue: false with reason: "Step limit exceeded"
• The default limit is implementation-defined but SHOULD be documented via introspection
• Implementations MUST support configuring the step limit

Stage 2 — Previous Step Outcome:

If the outcome field of the current record_execution_step call reports "failure", the evaluator SHOULD return continue: false.

• Pausing after failure prevents cascading errors from autonomous recovery attempts
• The agent SHOULD report the failure to the user or upstream system before retrying
• If outcome is omitted, this stage is skipped

Stage 3 — Action Pattern Matching:

Matches the nextActionHint string against configurable glob patterns:

• deny patterns → continue: false, stopped: true (triggers out-of-band verification — Section 8.8)
• requiresApproval patterns → continue: false (human review needed)
• autoApprove patterns → continue: true (skip remaining stages)
• Resolution order: deny > requiresApproval > autoApprove
• Unmatched actions fall through to Stage 4

Pattern examples:

{
  deny: ["drop_*", "delete_all*", "rm -rf*"],
  requiresApproval: ["delete_*", "*force*", "deploy_*", "git push*"],
  autoApprove: ["read_*", "list_*", "get_*", "search_*"]
}

Stage 4 — Safety Tier Evaluation:

Assigns a risk score (0-100) to the action and maps it to a safety tier:

The verify and danger_zone tiers both use the out-of-band verification protocol defined in Section 8.8. The difference is enforcement severity: verify sets continue: false (pause — the agent may resume after verification), while danger_zone sets stopped: true (hard block — the agent is blocked at the agent level until verified).

Risk scoring MAY use pattern matching against known dangerous operations, LLM-provided risk assessments, or adapter-specific heuristics.

Stage 5 — Risk Tolerance Threshold:

Compares the risk score against the agent's configured tolerance:

Actions with risk scores below the threshold in the advisory tier MAY proceed without pausing.

8.7.3 Agent Notification System

Notifications inform the agent of events that occurred since the last record_execution_step call. They are included in the AutonomyDirective response.

interface AgentNotification {
  type: NotificationType;
  message: string;               // Human-readable description
  metadata?: {
    operation?: string;          // Operation that triggered the event
    reason?: string;             // Detailed reason
    level?: string;              // Permission level that caused the block
    verificationId?: string;     // For verify and danger_zone challenges
  };
  timestamp: string;             // ISO 8601
}

type NotificationType =
  | "permission_pending"    // Gatekeeper blocked an operation
  | "autonomy_pause"        // Autonomy Evaluator paused execution
  | "danger_zone"           // Danger Zone hard block (system-wide broadcast)
  | "status"                // Informational status update
  | "error";                // Error condition

Notification sources:

• permission_pending: Generated when the Gatekeeper denies an operation that requires confirmation. Cleared when confirm_operation is called with a valid confirmation token for the blocked operation. Failed or invalid confirmation attempts do not clear the notification.
• autonomy_pause: Generated when the Autonomy Evaluator returns continue: false. Provides the reason and contributing factors. For confirm tier pauses, cleared when confirm_operation is called for the paused action. For verify tier pauses, MUST include verificationId in metadata; cleared when verify_challenge succeeds for the associated challenge ID or the challenge expires.
• danger_zone: Broadcast to ALL executing agents (including the affected agent) when any agent triggers a hard block (danger_zone tier or deny pattern match). MUST include the verificationId for the affected agent. Cleared when the blocked agent is unblocked via successful verify_challenge or admin override.

The notification system is pull-based: notifications accumulate between record_execution_step calls and are delivered in the response. There is no push channel.

Self-Approval Prevention: When permission_pending notifications expose the blocked operation name, the executing agent could attempt to call confirm_operation to approve its own blocked operations. Implementations MUST prevent self-approval — the entity confirming an operation MUST NOT be the same agent that triggered the block. Server-side controls such as caller identity validation, confirmation tokens bound to a human-only channel, or out-of-band confirmation delivery satisfy this requirement.

8.7.4 Configurable Elements

The following elements of the evaluation pipeline SHOULD be configurable per agent or per adapter:

Adapters SHOULD document their default configuration and supported configuration options via introspection.

8.7.5 Minimum Viable Implementation

Not all stages of the evaluation pipeline are equally important. The following defines the minimum requirements:

An implementation that supports only the Step Limit stage (with a configurable limit and hard pause at the threshold) is a conformant minimum viable implementation.

8.8 Out-of-Band Verification

When the Autonomy Evaluator assigns a verify or danger_zone safety tier (Section 8.7.2, Stage 4), the system MUST require out-of-band human verification before the agent may proceed. Out-of-band verification requires a human to provide a verification code through a channel that the AI cannot access, creating cryptographic proof that a human reviewed and approved the action. The verify tier pauses the agent; the danger_zone tier hard-blocks it.

8.8.1 Trigger Conditions

Out-of-band verification is triggered when:

• The safety tier evaluation assigns verify (risk score 61-85) or danger_zone (risk score 86-100), OR
• The nextActionHint matches a hard-block (deny) pattern configured in the adapter (Section 8.7.2, Stage 3)

For danger_zone and deny pattern triggers, the AutonomyDirective MUST return stopped: true and MUST include a danger_zone notification broadcast to all executing agents. For verify triggers, the AutonomyDirective returns continue: false (pause) without stopped: true — the agent is paused but not permanently blocked.

8.8.2 Challenge Protocol

The verification protocol follows these steps:

1. Challenge Generation:

• The adapter generates a verification code with at least 128 bits of entropy from a cryptographically secure random source
• The adapter generates a unique challenge ID (UUID v4 recommended)
• The code MUST be cryptographically unpredictable (not sequential, not time-based)

2. Out-of-Band Display:

• The verification code MUST be displayed through a channel inaccessible to the AI agent
• The code MUST NOT appear in any MCP response, tool result, _meta field, or log accessible to the AI
• Valid display channels include (but are not limited to):
  • OS-native dialogs (AppleScript on macOS, zenity on Linux, PowerShell on Windows)
  • Hardware security tokens
  • SMS or email to a registered operator
  • Dedicated security dashboard
• The AI agent receives only the challenge ID and a human-readable prompt — never the code itself
• The initial AutonomyDirective MUST include the challenge ID via a notification: autonomy_pause with metadata.verificationId for verify tier, or danger_zone with metadata.verificationId for danger_zone tier and deny pattern matches

3. Verification:

• The human provides the code via the verify_challenge operation with the challenge ID and code
• On successful verification, the blocked agent is unblocked and execution may resume
• On failed verification, the code is invalidated (one-time use)

4. Expiration:

• Verification challenges SHOULD expire after a configurable timeout (default: 5 minutes)
• Expired challenges MUST be treated as failed

8.8.3 Blocking Semantics

When an agent is hard-blocked by any event that sets stopped: true (a danger_zone safety tier assignment, a deny pattern match, or equivalent adapter-specific trigger):

• The AutonomyDirective returns stopped: true
• All subsequent execution operations for the blocked agent MUST be rejected until unblocked
• The blocked state MUST persist across server restarts (file-based or database storage)
• Only successful verification via verify_challenge or an explicit admin override can unblock the agent

Adapters MUST NOT allow an agent to bypass a hard block by starting a new execution. The block is applied at the agent level, not the execution level.

For verify tier challenges (where stopped is not true), the agent is paused rather than blocked. While a verify challenge is pending, subsequent record_execution_step calls for the same agent SHOULD return continue: false with the pending challenge ID in the reason field, until the challenge is completed or expires. Unlike hard blocks, verify pauses do not persist across server restarts and do not prevent starting new executions. When a verify challenge expires, the pause is lifted and subsequent record_execution_step calls SHOULD re-evaluate the action normally — if the same action is reported again, a new challenge is generated.

8.8.4 Channel Separation Requirements

The security of out-of-band verification depends entirely on channel separation. The verification code:

• MUST NOT appear in any MCP tool response or result
• MUST NOT appear in any _meta field of an MCP response
• MUST NOT be logged in any location accessible to the AI agent
• MUST NOT be included in error messages, debug output, or diagnostic information accessible to the AI
• MUST NOT be derivable from any information available to the AI (e.g., timestamps, sequential IDs)

Security Principle: Even a fully prompt-injected LLM that has been instructed to bypass safety checks cannot complete out-of-band verification, because the code exists only in a channel the LLM cannot observe.

8.8.5 Rate Limiting

Failed verification attempts SHOULD be rate-limited to prevent brute-force attacks:

• Implementations SHOULD allow no more than 10 failed attempts per 60-second window per agent
• After exceeding the rate limit, subsequent verification attempts SHOULD be rejected with an appropriate error
• The failure counter resets after the window expires (sliding or fixed window); however, implementations MAY apply progressive lockout (e.g., doubling the window duration) after repeated rate-limit violations
• Rate limit state SHOULD persist across server restarts
• Failed verification attempts SHOULD trigger security audit events

8.8.6 Implementation Flexibility

This specification defines the verification protocol, not the display mechanism. Implementations MAY use any display channel that satisfies the channel separation requirements (Section 8.8.4):

The only requirement is that the channel is inaccessible to the AI agent performing the action.

9. Type System

9.1 Protocol Types

MCP-AQL defines these protocol-level types:

SemanticCategory (enum)

CREATE | READ | UPDATE | DELETE | EXECUTE

OperationResult (union)

OperationSuccess | OperationFailure

See Appendix D: JSON Schemas for formal schema definitions.

9.2 Adapter Types

Adapters define their own domain-specific types, which MUST be discoverable via the introspect operation with query: "types".

9.3 Request Concurrency

MCP allows request pipelining, enabling clients to send multiple requests without waiting for responses. MCP-AQL defines ordering guarantees for batch operations (see Operations Reference Section 7) but does not mandate ordering for concurrent independent requests.

9.3.1 Concurrency Requirements

Adapters MUST document their concurrency behavior. The following concurrency categories are defined:

9.3.2 State-Modifying Operations

Adapters supporting concurrent state modification SHOULD implement optimistic concurrency control:

1. ETag/Version Response: Include _etag or _version field in responses for mutable resources
2. Precondition Request: Accept if_match parameter for conditional updates
3. Conflict Detection: Return CONFLICT_VERSION_MISMATCH error when precondition fails

Example response with version:

{
  "success": true,
  "data": {
    "id": "doc_123",
    "title": "My Document",
    "_etag": "W/\"a1b2c3d4\""
  }
}

Example conditional update:

{
  "operation": "update_document",
  "params": {
    "id": "doc_123",
    "title": "Updated Title",
    "if_match": "W/\"a1b2c3d4\""
  }
}

9.3.3 Concurrency Metadata

Adapters MAY expose concurrency behavior via introspection in protocol metadata:

{
  "_protocol": {
    "concurrency": "resource-locked",
    "supports_etag": true,
    "max_concurrent_requests": 10
  }
}

10. Conformance

10.1 Conformance Levels

Level 1: Basic Conformance

• MUST support at least one endpoint mode (semantic or single)
• MUST implement the introspect operation
• MUST use standard request/response formats
• MUST classify operations correctly into standard semantic categories
• MUST document each operation's exposed endpoint family and semantic category via introspection
• MUST reject operations sent to wrong endpoints in semantic endpoint mode

Level 2: Full Conformance

• MUST meet Level 1 requirements
• MUST support both semantic and single endpoint modes
• MUST pass the conformance test suite
• SHOULD implement field selection
• SHOULD implement batch operations

10.2 Claiming Conformance

Implementations claiming MCP-AQL conformance MUST:

1. State their conformance level
2. Document their operations via introspection
3. Document any extensions

10.3 Extensions

Implementations MAY extend MCP-AQL with additional:

• Features (field selection, batch operations, etc.)
• Response metadata fields

Extensions MUST be documented and MUST NOT conflict with core specification behavior.

Appendix A: Token Efficiency

A.1 Measured Token Costs

A.2 Introspection Pattern

Total context for 10 operations with introspection:
- Tool registration: ~1,100 tokens
- 10 × introspect calls: ~1,500 tokens
- Total: ~2,600 tokens (vs ~29,600 baseline)

Appendix B: References

Core Documentation

• Protocol Overview
• Operations Reference
• Endpoint Modes
• MCP Integration
• Introspection Specification
• Plugin Interface Contracts
• Adapter Element Type Specification

Implementation Documentation

• Architecture Overview (in mcpaql-adapter repo)
• Universal Adapter Runtime (in mcpaql-adapter repo)
• Plugin System Implementation (in mcpaql-adapter repo)
• Development Guide (in mcpaql-adapter repo)

Examples

• GitHub API Adapter (in examples repo)

Guides

• Protocol Comparison Guide

Process & Decision Records

• Architecture Decision Records

External References

• Model Context Protocol Specification (note: may be unreachable)
• RFC 2119 - Key words for use in RFCs

Appendix C: Change Log

Appendix D: JSON Schemas

Formal JSON Schema definitions are provided for validation:

Schemas use JSON Schema 2020-12 draft and are normative for this specification.