MCP-AQL Protocol Overview

MCP-AQL (Model Context Protocol - Agent Query Language) is a protocol that consolidates discrete MCP tools into a small number of semantic endpoint families, providing significant token reduction while maintaining full functionality. The standard semantic-endpoint profile is CRUDE (Create, Read, Update, Delete, Execute), but adapters MAY define alternate semantic endpoint families.

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

Protocol Summary

MCP-AQL defines a schema-driven operation dispatch protocol that:

1. Consolidates Operations - Many discrete tools into a small number of semantic endpoint families
2. Enables Discovery - GraphQL-style introspection for runtime operation discovery
3. Enforces Safety - Endpoint classification validates operation/endpoint matching
4. Supports Flexibility - Implementations MAY offer semantic endpoint mode with the standard CRUDE profile or alternate semantic endpoint families, or Single mode

+-------------------+
|    MCP Client     |
+--------+----------+
         |
         v
+-------------------+
|  MCP-AQL Layer    |
|  +-------------+  |
|  |  Gatekeeper |  |  Route Validation
|  +------+------+  |
|         |         |
|  +------v------+  |
|  |   Router    |  |  Endpoint Mapping
|  +------+------+  |
|         |         |
|  +------v------+  |
|  |   Schema    |  |  Operation Definitions
|  +------+------+  |
|         |         |
|  +------v------+  |
|  | Dispatcher  |  |  Handler Resolution
|  +-------------+  |
+--------+----------+
         |
         v
+-------------------+
| Target Handlers   |
+-------------------+

The CRUDE Pattern

MCP-AQL extends traditional CRUD with an EXECUTE endpoint, creating the CRUDE pattern:

Permission Characteristics

Each endpoint MUST have defined permission characteristics:

Implementations MUST classify operations according to these permission characteristics and MUST NOT allow an operation to be called through an endpoint that does not match its classification.

Why CRUDE not CRUD?

The EXECUTE endpoint exists because certain operations:

• Are inherently non-idempotent (calling execute twice creates two separate executions)
• Manage runtime state rather than persistent definitions
• Require lifecycle management (start, update progress, complete, resume)

CRUD (Resource Definitions)          EXECUTE (Runtime Lifecycle)
+--------+                           +-------------------+
| Create |-------------------------->| execute           |
+--------+                           +--------+----------+
| Read   |                                    |
+--------+                           +--------v----------+
| Update |                           | get_execution_state|
+--------+                           +--------+----------+
| Delete |                                    |
+--------+                           +--------v----------+
                                     | update_execution   |
                                     +--------+----------+
                                              |
                              +---------------+---------------+
                              |                               |
                     +--------v----------+           +--------v----------+
                     | complete_execution|           | continue_execution|
                     +-------------------+           +-------------------+

Note: This diagram shows a runtime lifecycle flow, not endpoint classification. Operations like get_execution_state that query execution state belong to the READ semantic category, not EXECUTE. In the standard CRUDE profile they are exposed on the READ endpoint. See CRUDE Pattern Classification for details.

Endpoint Modes

MCP-AQL supports two operational modes. Implementations MUST support at least one mode and SHOULD support both:

Semantic Endpoint Mode

The standard CRUDE profile exposes 5 separate endpoints, each with semantic meaning:

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 alternate semantic-endpoint profile can expose a different but still semantically legible set:

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

Advantages:

• Clear semantic grouping
• Endpoint-level permission control
• Clients MAY choose which endpoints to expose

Single Mode

Exposes 1 unified endpoint that routes internally:

mcp_aql - All operations through single entry point

Advantages:

• Minimal token footprint
• Simpler client integration
• Server-side routing enforcement

Implementations using Single Mode MUST still enforce endpoint classification internally. An operation classified as DELETE MUST NOT succeed if the implementation would not allow DELETE operations.

Token Efficiency

Token Reduction

The primary motivation for MCP-AQL is reducing the token cost of tool registration. Empirical measurements demonstrate:

Runtime Discovery

Instead of parsing many tool schemas at registration time, clients use introspection at runtime:

// Query all available operations
{ operation: "introspect", params: { query: "operations" } }

// Get details for a specific operation
{ operation: "introspect", params: { query: "operations", name: "create_entity" } }

// Query available types
{ operation: "introspect", params: { query: "types", name: "EntityType" } }

Implementations MUST support the introspect operation as a READ-category operation on a documented endpoint family.

Core Concepts

Schema-Driven Operations

Operations SHOULD be defined declaratively with:

• name - The operation identifier
• semantic_category - The standard CREATE/READ/UPDATE/DELETE/EXECUTE classification
• endpoint - The exposed endpoint family name
• description - Human-readable description
• params - Required and optional parameter definitions
• handler - Reference to the implementation handler

Gatekeeper

The Gatekeeper component enforces that operations are only callable through their designated endpoints. Implementations MUST validate that:

1. The operation exists
2. The operation is allowed on the requested endpoint
3. Required parameters are present

Introspection

MCP-AQL implementations MUST provide GraphQL-style introspection capabilities:

• List all available operations
• Get detailed information about specific operations
• Query available types and enumerations
• Discover parameter requirements

Request Flow

Standard Request

1. Client sends { operation, params } to endpoint
2. Gatekeeper validates operation is allowed on endpoint
3. Router resolves operation to handler
4. Schema validates required parameters
5. Dispatcher invokes handler with mapped parameters
6. Handler returns result
7. Response formatted as { success: true, data } or { success: false, error }

Response Format

All MCP-AQL operations MUST return discriminated responses:

Success:

{
  success: true,
  data: { /* operation result */ }
}

Failure:

{
  success: false,
  error: {
    code: "VALIDATION_ERROR",
    message: "Required parameter 'entity_name' is missing"
  }
}

Implementations SHOULD include an error code for programmatic handling and MUST include a human-readable message.

Batch Operations

MCP-AQL implementations MAY support batch operations for executing multiple operations in a single request.

Batch Request Format

{
  operations: [
    { operation: "create_entity", params: { name: "entity1" } },
    { operation: "create_entity", params: { name: "entity2" } },
    { operation: "activate_entity", params: { name: "entity1" } }
  ]
}

Batch Response Format

{
  success: true,
  results: [
    { index: 0, operation: "create_entity", result: { success: true, data: { /* ... */ } } },
    { index: 1, operation: "create_entity", result: { success: true, data: { /* ... */ } } },
    { index: 2, operation: "activate_entity", result: { success: true, data: { /* ... */ } } }
  ],
  summary: { total: 3, succeeded: 3, failed: 0 }
}

When batch operations are supported, implementations:

• MUST process operations in order
• MUST include results for all operations, including failures
• SHOULD continue processing after individual operation failures
• MAY provide a configuration option to stop on first failure

Conformance

An MCP-AQL implementation is conformant if it:

1. Implements at least one endpoint mode (semantic or Single)
2. Enforces endpoint classification for all operations
3. Provides the introspect operation as a READ-category operation on a documented endpoint family
4. Returns discriminated responses for all operations
5. Validates required parameters before dispatching

Related Specifications

• Operations Reference - Complete operation reference
• Introspection - Introspection system specification
• MCP Integration - MCP protocol integration specification
• Response Format - Response format specification