PRELIMINARY PUBLIC DRAFT

MCP-AQL tells AI clients what operations mean, not just how to call them

MCP-AQL adds semantic routing on top of MCP transport, so operation intent is explicit at the protocol layer instead of buried in tool descriptions. Clients can distinguish safe reads from destructive deletes by endpoint alone, while cutting tool-definition token overhead by about 85-96%.

Start With The Quick Path Open Documentation Library Browse Full Spec Reference Public Launch Checklist

Why MCP-AQL Matters

MCP-AQL makes operation intent visible at the protocol layer, keeps discovery runtime-driven, and gives clients enough structure to reason about safety without guessing from prose.

MCP's semantics gap

In plain MCP, get_user and drop_database are structurally identical. The only clue about safety or intent is the human-written description field.

Semantic routing in MCP-AQL

In MCP-AQL, routing an operation to READ guarantees side-effect-free intent, while routing to DELETE declares destructive intent at the protocol layer.

Policy and agent benefit

Clients, LLMs, and policy systems can make decisions from the endpoint alone instead of burning tokens trying to infer behavior from descriptive text.

Token Efficiency In One View

The fastest way to understand why the protocol exists is to look at the registration footprint. MCP-AQL moves capability discovery to runtime, so clients do not pay the full schema cost up front for operations they may never use.

Configuration Approximate token cost Reduction What the client gets
Discrete tools (50+) ~30,000 tokens Baseline Every tool definition loaded up front
CRUDE mode (5 endpoints) ~4,500 tokens ~85% Semantic endpoints plus runtime discovery
Single mode (1 endpoint) ~1,100 tokens ~96% One routed entrypoint plus runtime discovery

The deeper discovery math lives in the spec too: the introspection guide models a typical path dropping from about 29,600 tokens for discrete tools to about 2,600 total for MCP-AQL plus on-demand introspection over ten operations.

Getting Started

Start here for the shortest path from the core idea to the draft spec, operational rules, and current launch posture.

Protocol Coverage

Explore the protocol by core behavior, safety model, validation surface, implementation guidance, and ecosystem reference material.

Core Protocol Surface

  • Request and response contract model
  • CRUDE and single-endpoint operation routing
  • Runtime introspection for discoverability
  • Canonical verbs, parameter rules, and unknown-param handling
Open Protocol Core

Error And Response Surface

  • Structured error envelope with code and message
  • MVP registry plus phase-1 robustness concerns
  • Current spec alignment work for error surfacing
Open Error Model

Security And Safety Surface

  • Gatekeeper trust-level mediation
  • Danger-level and confirmation token flows
  • Execution loop controls and safety boundaries
  • Batch/resource exhaustion protections
Open Security Model

Conformance And Tooling Surface

  • Required behavior for claiming MCP-AQL compatibility
  • Current conformance test and validator status
  • MVP "on-spec" validator roadmap in tools repo
Open Conformance Guide

Implementation And Ecosystem Surface

  • Reference runtime and plugin architecture docs
  • Adapter schema and plugin contract requirements
  • Generator/output-policy and provenance requirements
Open Adapter Contracts

How MCP-AQL Differs From Familiar Patterns

See where MCP-AQL aligns with familiar patterns, and where its semantic routing and runtime discovery make it different.

MCP

MCP-AQL is a protocol layer on top of MCP transport, not a replacement. The difference is semantic endpoints, runtime discovery, and built-in safety classification instead of prose-only intent.

Read the guided explanation

GraphQL

Both use runtime discovery, but GraphQL requires a schema language and type system. MCP-AQL keeps the existing MCP transport and adds semantic routing without introducing a new SDL.

Open the comparison guide

REST

REST uses HTTP verbs for semantics. MCP-AQL applies a similar idea to the MCP tool layer, where HTTP verbs do not exist, so intent stays visible even when everything would otherwise look like an undifferentiated tool call.

See the detailed comparison

Full Website-Hosted Spec Reference

Read the canonical spec material on-site, with the same navigation and search used across the rest of the documentation portal.

What changed

  • The full reference is generated directly from MCPAQL/spec/docs.
  • Versioned drafts, support docs, and topic pages are hosted under the website's own navigation and search.
  • Summary pages still help people orient quickly, but the detailed material is no longer repo-only.

Reference Adapter Docs On-Site

Reference adapter architecture, runtime, testing, and ADR material are available on-site alongside the protocol docs.

What changed

  • The reference adapter repo docs are hosted under the website's own navigation and search.
  • Architecture, runtime, testing, migration, and ADR content no longer requires a GitHub jump-out.
  • Adapter pattern pages can now route into implementation docs instead of ending at conceptual guidance.

Current Draft Blockers

These live spec issues still shape compatibility claims, launch language, and what the public draft can promise today.

Why they matter publicly

  • They define what the site can honestly call compatible today.
  • They affect batch safety, machine-readable errors, and MCP parity messaging.
  • They keep the draft positioned as real, useful, and still in progress.

Repository Map

Each repository has a specific role in the protocol, reference implementations, tooling, and launch readiness work.

spec

Canonical

Normative protocol text, schemas, and versioned draft authority.

Open Repository

mcpaql-adapter

Reference Runtime

Schema-driven dispatch, runtime architecture, and plugin contracts in practice.

Open Adapter Docs

examples

Reference Adapters

Pattern examples and candidate public adapters for launch-phase demonstration.

Open Repository

adapter-generator

Generator Track

Output policy, provenance, and generation constraints for derived adapters.

Open Repository

tools

Validation Track

Conformance CLI and on-spec validator workstream for third-party implementations.

Open Repository

website

Documentation Portal

Public-facing browse and search layer for protocol launch and post-launch evolution.

Open Repository

Adapter Pattern Pages

Start from the adapter-pattern hub, then move into the specific environment pages that match the target system you are adapting.

Adapter Patterns Overview

Start here

Top-level guide to choosing the right target-system pattern before diving into the child pages.

MCP Server Pattern

Draft guidance

Native MCP server consolidation patterns.

Operating System Pattern

Draft guidance

Permission-aware local execution boundaries.

Application Pattern

Draft guidance

Application APIs mapped into semantic operations.

Cloud Service Pattern

Draft guidance

External API adaptation with quota and resilience posture.

Website Pattern

Draft guidance

Web retrieval and action orchestration guidance.