PROTOCOL CORE

Normative Foundations

MCP-AQL defines a protocol layer for operation consolidation and runtime discovery. Canonical authority is the versioned specification in MCPAQL/spec; this page is a readable map of the same core requirements.

Normative Spec Spec Docs Index

On this page

Jump to a section

Use the outline to move through longer pages without losing your place.

  1. Protocol Scope
  2. Why semantic endpoints matter
  3. CRUDE Endpoint Model
  4. Endpoint Modes
  5. Request And Response Contract
  6. Runtime Discovery
  7. Operational rules readers usually miss

Related reading

Protocol Scope

MCP-AQL specifies wire-level operation request/response behavior, endpoint semantics, introspection shape, and operation classification guidance. It intentionally does not prescribe domain-specific operation sets.

  • Authority source: versioned specification document
  • Informative docs: support design and implementation choices
  • Adapter-specific operations: declared by each implementation

Why semantic endpoints matter

MCP tool calls are structurally flat

In plain MCP, all tools share the same call shape. A reader, client, or policy system cannot reliably distinguish get_user from drop_database without inspecting descriptions and guessing from naming.

MCP-AQL makes intent structural

In MCP-AQL, the endpoint is part of the contract. READ declares side-effect-free behavior, DELETE declares destructive intent, and EXECUTE declares a lifecycle or stateful flow.

The CRUDE model is not just an organizational convenience. It gives clients, LLMs, and policy systems protocol-level safety hints without relying on author-written descriptions.

CRUDE Endpoint Model

Endpoint Intent Safety posture
Create Additive operations creating new state Non-destructive
Read Safe queries without side effects Read-only
Update Operations modifying existing state Mutating
Delete Removal operations Destructive
Execute Runtime lifecycle and side-effectful flows Stateful / non-idempotent

Endpoint Modes

CRUDE Mode (5 endpoints)

Semantic separation by operation effect category. Maximizes explicit routing intent.

mcp_aql_create
mcp_aql_read
mcp_aql_update
mcp_aql_delete
mcp_aql_execute

Single Mode (1 endpoint)

One entrypoint for all operations, with internal routing based on operation metadata.

mcp_aql

Request And Response Contract

Request Shape

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

Public parameter names are snake_case. Runtime values are passed in params and aligned to introspection-declared parameter definitions.

Response Shape

{ "success": true,  "data": { ... } }
{ "success": false, "error": { ... } }

Conforming implementations use discriminated response unions so clients can branch behavior predictably.

Runtime Discovery

Why it changes the economics

MCP-AQL keeps the public endpoint surface small and makes runtime discovery part of the protocol through introspect. That means the protocol does not require a large up-front tool-definition payload in order to begin operating. Some MCP clients already have progressive loading, but the benefit depends on which client you are using. MCP-AQL makes on-demand discovery available in a client-agnostic way, so the practical benefit carries across MCP-speaking clients instead of depending on a particular client implementation.

Typical discovery path

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

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

The spec models this pattern as about 50 tokens to list operations and about 100 tokens to fetch the details for one relevant operation.

Operational rules readers usually miss

Naming and parameter rules

  • Operation names are case-sensitive snake_case identifiers.
  • Public parameter names are snake_case, even if implementations accept aliases internally.
  • Unknown parameters should be rejected instead of ignored so clients can correct requests.

Batch and payload considerations

  • Batch operations are first-class, but launch messaging should still treat resource-limit requirements as in progress.
  • Payload size, encoding, and response shape constraints are part of interoperability, not optional polish.
  • Issue #197 tracks the remaining batch-limit hardening work.