MCP-AQL Operations Specification

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

Document Status: This document is informative. For normative requirements, see MCP-AQL Specification v1.0.0.

Abstract

This document specifies how operations are defined, documented, and invoked in MCP-AQL adapters. It covers the operation input format, response format, parameter conventions, operation schemas, batch operations, and error handling patterns.

1. Conformance Requirements

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.

An MCP-AQL adapter is conformant if it implements:

1. The operation input format as specified in Section 2
2. The discriminated response format as specified in Section 3
3. The introspect operation as specified in Section 9
4. Correct endpoint routing based on operation semantics (Section 6)

2. Operation Input Format

2.1 Standard Input Structure

All operations MUST follow a consistent input structure:

{
  "operation": "<operation_name>",
  "params": {
    // Operation-specific parameters
  }
}

2.2 Required Fields

The operation field MUST be a non-empty string matching a defined operation name.

Terminology Note: The request field params (an object) carries runtime parameter values. The introspection field parameters (an array of ParameterInfo) describes the accepted parameter definitions. The keys of params correspond to the name field of each ParameterInfo entry. See Introspection — OperationDetails.

2.3 Parameter Resolution

Adapters MAY support parameter resolution from multiple locations. The RECOMMENDED resolution order is:

1. params.<parameter_name> (preferred)
2. Top-level <parameter_name> (convenience)

When the same parameter appears at multiple levels, the value in params takes precedence.

Example - Equivalent Requests:

// Parameters in params object (RECOMMENDED)
{
  operation: "get_item",
  params: { item_id: "123" }
}

// Parameters at top level (also valid)
{
  operation: "get_item",
  item_id: "123"
}

2.4 Case Sensitivity

Operation names MUST be case-sensitive. Operation names MUST use snake_case (a lowercase letter followed by lowercase letters, digits, and underscores), matching the schema pattern ^[a-z][a-z0-9_]*$.

3. Response Format

3.1 Discriminated Union Result

All operations MUST return a discriminated union response. The success field serves as the discriminator.

type OperationResult = OperationSuccess | OperationFailure;

interface OperationSuccess {
  success: true;
  data: unknown;   // Operation-specific payload
  error?: never;   // MUST NOT be present
}

interface OperationFailure {
  success: false;
  error: ErrorDetail;  // Structured error information
  data?: never;        // MUST NOT be present
}

interface ErrorDetail {
  code: string;     // Machine-readable error code (e.g., "NOT_FOUND_RESOURCE")
  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.

3.2 Success Response

A successful operation MUST return:

• success: The boolean value true
• data: The operation result (type varies by operation)

{
  "success": true,
  "data": {
    "id": "item_123",
    "name": "Example Item",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

3.3 Failure Response

A failed operation MUST return:

• success: The boolean value false
• error: A structured error object with code and message

{
  "success": false,
  "error": {
    "code": "NOT_FOUND_RESOURCE",
    "message": "Item with ID 'item_999' not found",
    "details": {
      "resource_type": "item",
      "resource_id": "item_999"
    }
  }
}

3.4 Response Metadata

Implementations MAY include metadata in responses:

{
  "success": true,
  "data": { ... },
  "_meta": {
    "requestId": "req_abc123",
    "duration_ms": 42
  }
}

Metadata fields MUST be prefixed with underscore (_) to distinguish them from the operation payload.

4. Parameter Conventions

4.1 Naming Convention

All public-facing parameter names MUST use snake_case (matching the pattern ^[a-z][a-z0-9_]*$):

// Correct
{ item_id: "123", created_after: "2024-01-01" }

// Non-conforming
{ itemId: "123", createdAfter: "2024-01-01" }

For backward compatibility, adapters MAY accept camelCase variants as aliases and normalize them to snake_case internally, but the canonical parameter names MUST be snake_case.

4.2 Common Parameter Patterns

Adapters SHOULD use consistent patterns for common functionality:

Text Search:

{
  query: "api reviewer"
}

Pagination (cursor-based):

{
  first: 25,
  after: "cursor_abc123"
}

Pagination (offset-based compatibility style):

{
  limit: 25,
  offset: 50
}

Filtering:

{
  filter: {
    status: "active",
    created_after: "2024-01-01"
  }
}

Sorting:

{
  sort: {
    field: "created_at",
    order: "desc"  // "asc" or "desc"
  }
}

Field Selection:

{
  fields: "minimal"  // Or ["id", "name", "email"]
}

Aggregations:

{
  aggregate: {
    total: { count: true },
    by_status: { group_by: "status", count: true }
  }
}

4.3 Required vs Optional Parameters

Each parameter MUST be documented as either required or optional. The operation schema (Section 5) specifies this via the required attribute.

4.4 Cross-Cutting Parameters

Cross-cutting parameters are parameters that apply across multiple operations. To ensure consistent discoverability, implementations SHOULD define these parameters once and reference them consistently.

For the preferred collection-query contract that combines text search, filters, sorting, pagination, and field selection, see Collection Querying. For summary-oriented server-side aggregation, see Aggregations. For adapter-declared derived values, see Computed Fields. For graph traversal and relationship exploration, see Relationship Queries.

4.4.1 Standard Cross-Cutting Parameters

4.4.2 Shared Parameter Definitions

Implementations SHOULD use a shared definition mechanism to ensure consistency:

shared_parameters:
  fields:
    name: "fields"
    type: "string | string[]"
    required: false
    description: "Field selection: preset ('minimal', 'standard', 'full') or array of field paths"

  filter:
    name: "filter"
    type: "object"
    required: false
    description: "Structured filtering criteria"

  sorting:
    name: "sort"
    type: "object"
    required: false
    description: "Sort object with 'field' and 'order'"

  cursor_pagination:
    - name: "first"
      type: "number"
      required: false
      description: "Maximum results to return from the start"
      default: 25
    - name: "after"
      type: "string"
      required: false
      description: "Opaque cursor to continue after"
    - name: "last"
      type: "number"
      required: false
      description: "Maximum results to return from the end"
    - name: "before"
      type: "string"
      required: false
      description: "Opaque cursor to continue before"

  offset_pagination:
    - name: "limit"
      type: "number"
      required: false
      description: "Maximum results to return"
      default: 25
    - name: "offset"
      type: "number"
      required: false
      description: "Number of results to skip"
      default: 0

  page_pagination:
    - name: "page"
      type: "number"
      required: false
      description: "Page number (1-indexed)"
      default: 1
    - name: "page_size"
      type: "number"
      required: false
      description: "Items per page"
      default: 25

These shared_parameters keys are illustrative rather than normative. Adapters that already expose $ref paths such as #/shared_parameters/pagination or legacy sort/order groups SHOULD preserve those existing references, or provide documented aliases, instead of renaming them silently.

4.4.3 Pagination Response Structure

Operations returning paginated collections SHOULD include explicit pagination metadata in the response so clients can continue the query without reverse-engineering adapter-specific fields.

Preferred cursor-based response:

{
  "success": true,
  "data": {
    "items": [
      { "name": "alice", "status": "active" },
      { "name": "bob", "status": "active" }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "cursor_001",
      "endCursor": "cursor_002",
      "totalCount": 142
    }
  }
}

Cursor-paginated MCP-AQL-native operations SHOULD use the pageInfo connection-style metadata described in Pagination.

Page-based compatibility response:

{
  "success": true,
  "data": {
    "items": [
      { "name": "alice", "status": "active" },
      { "name": "bob", "status": "active" }
    ],
    "pagination": {
      "page": 2,
      "page_size": 25,
      "total_items": 142,
      "total_pages": 6,
      "has_more": true
    }
  }
}

Offset-based compatibility response:

{
  "success": true,
  "data": {
    "items": [
      { "name": "alice", "status": "active" },
      { "name": "bob", "status": "active" }
    ],
    "pagination": {
      "limit": 25,
      "offset": 50,
      "returned": 25,
      "total_items": 142,
      "has_more": true
    }
  }
}

Recommended metadata by pagination style:

If computing totals is expensive, adapters MAY omit total_items, total_pages, or totalCount and rely on has_more, hasNextPage, or hasPreviousPage instead.

Compatibility metadata examples use snake_case field names to align with MCP-AQL's public naming convention for adapter-facing request and response fields.

4.4.4 Cross-Cutting Parameter Consistency (SHOULD)

When a parameter applies to multiple operations:

1. The parameter name SHOULD be identical across operations
2. The parameter type SHOULD be identical across operations
3. The parameter description SHOULD be semantically equivalent
4. Default values SHOULD be consistent where applicable

4.4.5 Introspection Integration

When introspection is queried, shared parameters SHOULD be expanded inline with their full definitions. This ensures LLMs see consistent documentation regardless of which operation they query.

Example - Operations referencing shared parameters:

operations:
  list_items:
    params:
      - $ref: "#/shared_parameters/fields"
      - $ref: "#/shared_parameters/filter"
      - $ref: "#/shared_parameters/cursor_pagination"

  search_items:
    params:
      - $ref: "#/shared_parameters/fields"
      - $ref: "#/shared_parameters/filter"
      - $ref: "#/shared_parameters/sorting"
      - $ref: "#/shared_parameters/cursor_pagination"
      - name: "query"
        type: "string"
        required: true
        description: "Search query"

Example - Inline expansion returned to clients:

operations:
  search_items:
    params:
      - name: "fields"
        type: "string | string[]"
        required: false
        description: "Field selection: preset ('minimal', 'standard', 'full') or array of field paths"
      - name: "filter"
        type: "object"
        required: false
        description: "Structured filtering criteria"
      - name: "sort"
        type: "object"
        required: false
        description: "Sort object with 'field' and 'order'"
      - name: "first"
        type: "number"
        required: false
        description: "Maximum results to return from the start"
      - name: "after"
        type: "string"
        required: false
        description: "Opaque cursor to continue after"
      - name: "query"
        type: "string"
        required: true
        description: "Search query"

4.5 UPDATE Input Pattern

UPDATE operations SHOULD use a nested input object to separate identifier parameters from updateable fields. See MCP-AQL Specification Section 4.5 for normative requirements including deep-merge semantics and field removal. See ADR-002 for design rationale.

5. Operation Schema Definition

5.1 Schema Structure

Each operation MUST be defined by a schema that specifies its behavior, parameters, and routing. Conformant adapters MUST validate requests against operation schemas before execution.

Schema Properties:

5.2 Parameter Schema

Each parameter in the params object MUST include:

Additional properties MAY be included:

5.3 Example Schema Definition

// Schema for a create operation
{
  create_item: {
    endpoint: "CREATE",
    description: "Create a new item in the system",
    params: {
      name: {
        type: "string",
        required: true,
        description: "Item name"
      },
      category: {
        type: "string",
        required: true,
        description: "Item category",
        enum: ["product", "service", "subscription"]
      },
      price: {
        type: "number",
        required: false,
        minimum: 0,
        description: "Item price in cents"
      },
      metadata: {
        type: "object",
        required: false,
        description: "Additional item metadata"
      }
    }
  }
}

5.4 Parameter Validation

Before executing an operation, adapters MUST:

1. Verify all required parameters are present
2. Validate parameter types match the schema
3. Reject unknown parameters not defined in the operation schema (see MCP-AQL Specification Section 4.6)
4. Apply any constraints (enum, minimum, maximum, pattern)
5. Apply default values for missing optional parameters

Note: Unknown parameter rejection (step 3) occurs before applying defaults (step 5) to ensure that typos or hallucinated parameters are caught early, before any processing occurs.

Validation failures MUST return an error response (not throw exceptions).

6. Semantic Endpoint Assignment

6.1 Endpoint Semantics

Operations MUST be assigned to endpoints based on their semantics:

The standard CRUDE profile is the default semantic-endpoint profile for these semantics, but semantic endpoint mode MAY expose alternate semantic-endpoint profiles when the endpoint names still communicate intent clearly to clients.

Standard and Alternate Semantic-Endpoint Profiles

These alternate profiles remain in-spec because the endpoints are still semantically legible to an LLM or client. What matters is not that every adapter uses CRUDE, but that the chosen endpoint set communicates where an operation belongs.

6.2 Common Verbs by Endpoint

Each endpoint has canonical verbs (shown in bold) that SHOULD be used for standard operations, plus additional verbs for domain-specific semantics. See Section 8.5 of the normative specification for naming requirements.

Note: The introspect operation is a reserved protocol operation and is not listed as a common verb. See Section 8.5.4 of the normative specification.

6.3 Endpoint Routing Enforcement

Adapters MUST validate that operations are invoked via their designated endpoint. An operation assigned to CREATE MUST NOT execute when called via the DELETE endpoint.

When an operation is routed to the wrong endpoint, adapters SHOULD return an error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ENDPOINT_MISMATCH",
    "message": "Operation 'create_item' must use CREATE endpoint, not DELETE",
    "details": {
      "operation": "create_item",
      "expected_endpoint": "CREATE",
      "actual_endpoint": "DELETE"
    }
  }
}

6.4 Dangerous Operation Classification

Operations with significant consequences SHOULD be marked with dangerous: true in their schema. This enables clients to:

• Display confirmation prompts
• Log operations with enhanced audit trails
• Apply additional authorization checks

Examples of dangerous operations:

• Bulk deletions
• Data truncation
• Irreversible state changes
• Operations affecting production data

7. Batch Operations

7.1 Batch Request Format

Adapters MAY support batch operations. When supported, the format MUST be:

{
  "operations": [
    { "operation": "create_item", "params": { "name": "Item A", "category": "product" } },
    { "operation": "create_item", "params": { "name": "Item B", "category": "service" } },
    { "operation": "create_item", "params": { "name": "Item C", "category": "product" } }
  ]
}

7.2 Batch Response Format

Batch responses MUST include individual results for each operation:

{
  "success": true,
  "data": null,
  "results": [
    { "index": 0, "operation": "create_item", "result": { "success": true, "data": { "id": "item_1" } } },
    { "index": 1, "operation": "create_item", "result": { "success": true, "data": { "id": "item_2" } } },
    { "index": 2, "operation": "create_item", "result": { "success": false, "error": { "code": "CONFLICT_ALREADY_EXISTS", "message": "Item with name 'Item C' already exists" } } }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}

7.3 Batch Execution Semantics

Conformant batch implementations MUST follow these semantics:

1. Operations execute in array order
2. Failure of one operation MUST NOT prevent subsequent operations from executing
3. Each operation result is independent
4. The overall success is true if the batch completed processing (even with individual failures)
5. The overall success is false only for batch-level errors (malformed request, authentication failure)

7.4 Cross-Endpoint Batching

When using semantic endpoint mode (separate endpoint families), batch operations SHOULD be constrained to a single endpoint family:

• All operations assigned to the same endpoint family together in one batch
• For the CRUDE profile, all CREATE operations together in one batch to the CREATE endpoint, all READ operations together in one batch to the READ endpoint, and so on

Mixing operations across endpoints in a single batch is NOT RECOMMENDED. Implementations MAY reject mixed batches or MAY process them with explicit endpoint routing per operation.

7.5 Confirmation-Gated Batch Operations

When a batch operation encounters a CONFIRMATION_REQUIRED response, special handling is needed to maintain state consistency.

7.5.1 The Problem

Consider a batch where operations depend on each other:

{
  "operations": [
    { "operation": "delete_user", "params": { "user_id": "alice" } },
    { "operation": "send_notification", "params": { "user_id": "alice", "message": "Account deleted" } }
  ]
}

If delete_user requires confirmation, executing send_notification anyway would create inconsistent state (notification sent, but user not deleted).

7.5.2 Batch Halting (RECOMMENDED)

When an operation returns CONFIRMATION_REQUIRED, the batch SHOULD halt:

1. Operations before the gated operation execute normally
2. The gated operation returns CONFIRMATION_REQUIRED with a confirmation token
3. Subsequent operations do NOT execute
4. Response includes partial results and continuation information

{
  "success": true,
  "data": null,
  "results": [
    { "index": 0, "operation": "update_user", "result": { "success": true, "data": { "id": "alice" } } }
  ],
  "halted_at": {
    "index": 1,
    "operation": "delete_user",
    "result": {
      "success": false,
      "error": {
        "code": "CONFIRMATION_REQUIRED",
        "message": "This operation requires confirmation",
        "details": {
          "operation": "delete_user",
          "danger_level": "destructive",
          "reasons": ["Permanently deletes user account and associated data"],
          "confirmation_token": "conf_abc123",
          "expires_at": "2026-02-04T12:05:00Z"
        }
      }
    }
  },
  "pending_operations": [
    { "index": 2, "operation": "send_notification", "params": { "user_id": "alice", "message": "Account deleted" } }
  ],
  "summary": {
    "total": 3,
    "succeeded": 1,
    "failed": 0,
    "halted": 1,
    "pending": 1
  }
}

7.5.3 Continuation After Confirmation

To continue after the user confirms, submit a new batch starting from the halted operation with the confirmation token:

{
  "operations": [
    {
      "operation": "delete_user",
      "params": {
        "user_id": "alice",
        "confirmation_token": "conf_abc123"
      }
    },
    {
      "operation": "send_notification",
      "params": { "user_id": "alice", "message": "Account deleted" }
    }
  ]
}

Clients MAY use the pending_operations array from the halted response to construct the continuation batch.

7.5.4 Alternative: Skip and Continue (MAY)

Adapters MAY implement skip-and-continue behavior, where the gated operation is skipped and subsequent operations execute.

Mode Selection: Whether an adapter uses halt-and-wait (recommended) or skip-and-continue is an adapter configuration decision, not a per-request option. Clients can detect which mode is in use by examining the response:

• Halt mode: Response includes halted_at and pending_operations
• Skip mode: Response includes results for all operations, with status: "pending_confirmation" on gated operations

{
  "success": true,
  "data": null,
  "results": [
    { "index": 0, "operation": "update_user", "result": { "success": true, "data": { "id": "alice" } } },
    { "index": 1, "operation": "delete_user", "result": { "success": false, "error": { "code": "CONFIRMATION_REQUIRED", ... } }, "status": "pending_confirmation" },
    { "index": 2, "operation": "send_notification", "result": { "success": true, "data": {} } }
  ],
  "summary": { "total": 3, "succeeded": 2, "failed": 0, "pending_confirmation": 1 }
}

Warning: Skip-and-continue risks inconsistent state when operations depend on each other. This approach is NOT RECOMMENDED unless operations are known to be independent.

7.5.5 Semantics

For batch processing purposes:

• CONFIRMATION_REQUIRED is NOT a failure — it is a halting condition
• The batch overall success is true (batch processing succeeded; an operation requires confirmation)
• Halted batches include halted_at and pending_operations for continuation
• The summary.halted count indicates operations that triggered halting
• The summary.pending count indicates operations that did not execute

See Confirmation Token Specification for token lifecycle details and CONFIRMATION_REQUIRED Error Code for the complete response format.

8. Error Handling

8.1 Error Categories

Adapters MUST categorize errors using structured error codes. The table below shows error categories and their corresponding codes:

See Structured Error Codes Specification for detailed error code definitions and usage.

8.2 Error Response Structure

All error responses MUST use structured error objects:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND_RESOURCE",
    "message": "Item 'item_999' not found",
    "details": {
      "resource_type": "item",
      "resource_id": "item_999"
    }
  }
}

The error object:

• MUST include code - A machine-readable error code from the error code taxonomy
• MUST include message - A human-readable error message
• MAY include details - Additional contextual information for debugging

See Structured Error Codes Specification for the complete error code registry and usage guidelines.

8.3 Standard Error Codes

Adapters MUST use standardized error codes for programmatic handling. Common codes include:

See Structured Error Codes Specification for the complete error code registry including Phase 1 robustness codes.

8.4 Error Message Guidelines

Error messages SHOULD be:

1. Actionable: Tell the user what to do to fix the problem
2. Specific: Include relevant identifiers and values
3. Safe: Never expose sensitive information (passwords, tokens, internal paths)

9. The introspect Operation

9.1 Required Implementation

Every MCP-AQL adapter MUST implement the introspect operation as a READ-category operation on a documented endpoint family. This operation enables runtime discovery of available operations and types.

9.2 Operation Schema

{
  introspect: {
    endpoint: "READ",
    description: "Discover available operations and types",
    params: {
      query: {
        type: "string",
        required: true,
        enum: ["operations", "types"],
        description: "What to introspect"
      },
      name: {
        type: "string",
        required: false,
        description: "Specific operation or type name for detailed info"
      }
    }
  }
}

9.3 Query Types

List all operations:

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

Get operation details:

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

List all types:

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

Get type details:

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

9.4 Operations Response

When query is "operations" without a name:

{
  "success": true,
  "data": {
    "operations": [
      {
        "name": "create_item",
        "semantic_category": "CREATE",
        "endpoint": "manage",
        "description": "Create a new item"
      },
      {
        "name": "list_items",
        "semantic_category": "READ",
        "endpoint": "query",
        "description": "List all items"
      },
      {
        "name": "update_item",
        "semantic_category": "UPDATE",
        "endpoint": "manage",
        "description": "Update item properties"
      },
      {
        "name": "delete_item",
        "semantic_category": "DELETE",
        "endpoint": "manage",
        "description": "Delete an item"
      },
      {
        "name": "introspect",
        "semantic_category": "READ",
        "endpoint": "query",
        "description": "Discover available operations"
      }
    ]
  }
}

9.5 Operation Details Response

When query is "operations" with a name:

{
  "success": true,
  "data": {
    "operation": {
      "name": "create_item",
      "semantic_category": "CREATE",
      "endpoint": "manage",
      "mcpTool": "mcp_aql_manage",
      "description": "Create a new item",
      "permissions": {
        "readOnly": false,
        "destructive": false
      },
      "parameters": [
        {
          "name": "name",
          "type": "string",
          "required": true,
          "description": "Item name"
        },
        {
          "name": "category",
          "type": "string",
          "required": true,
          "description": "Item category",
          "enum": ["product", "service", "subscription"]
        },
        {
          "name": "price",
          "type": "number",
          "required": false,
          "minimum": 0,
          "description": "Item price in cents"
        }
      ],
      "returns": {
        "name": "Item",
        "kind": "object",
        "description": "Newly created item"
      },
      "examples": [
        {
          "description": "Create a basic item",
          "request": {
            "operation": "create_item",
            "params": {
              "name": "Widget",
              "category": "product"
            }
          }
        }
      ]
    }
  }
}

9.6 Types Response

When query is "types":

{
  "success": true,
  "data": {
    "types": [
      {
        "name": "ItemCategory",
        "kind": "enum",
        "values": ["product", "service", "subscription"]
      },
      {
        "name": "Item",
        "kind": "object",
        "fields": [
          { "name": "id", "type": "string" },
          { "name": "name", "type": "string" },
          { "name": "category", "type": "ItemCategory" },
          { "name": "price", "type": "number" }
        ]
      }
    ]
  }
}

References

• MCP-AQL Specification v1.0.0-draft
• CRUDE Pattern Specification
• Introspection Specification