AQL MCP server
Commit Oct 18, 2026Reduces LLM token consumption by consolidating multiple MCP tools into unified semantic endpoint families using a structured query language.
Also known as MCPAQL/spec
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 18, 2026
- License
- AGPL-3.0
What is AQL MCP?
AQL reduces LLM token consumption by consolidating multiple MCP tools into unified semantic endpoint families using a structured query language.
Summary generated from the project's README
About AQL MCP server
Developers looking to minimize token costs when using large sets of tools can use this specification to consolidate multiple MCP tools into unified semantic endpoint families. By moving away from discrete tool definitions, which can consume up to 30,000 tokens for 50 tools, this approach achieves approximately 96% token reduction through a single endpoint or a structured CRUDE profile.
This system uses a structured query language to facilitate communication between AI models and context-providing services. It provides a unified query syntax and GraphQL-style introspection for on-demand operation discovery at runtime. Users can implement different profiles such as database-oriented, hardware-oriented, or the standard CRUDE pattern, which includes Create, Read, Update, Delete, and Execute endpoints. The implementation includes a compiler for schema-driven dispatch and an adapter generator to help manage complex workflows like security or code execution.
What you can do with it
- 1Discovering available operations at runtimeUse introspection to let an AI client query the specific operations and parameters available in an adapter.
- 2Managing stateful runtime operationsPerform non-idempotent lifecycle tasks using the specialized Execute endpoint within a semantic family.
- 3Optimizing response payload sizesLimit the amount of data returned to the model by selecting specific fields during a query.
Written from the project's README. Every use case is checked against a quote from it.
README
View on GitHubMCP-AQL Specification
Model Context Protocol - Advanced Agent API Adapter Query Language
MCP-AQL is both a protocol specification and a concrete implementation toolkit, including an interrogator (introspection), compiler (schema-driven dispatch), and adapter generator.
Overview
MCP-AQL is a protocol specification that consolidates multiple MCP (Model Context Protocol) tools into semantic endpoint families, providing approximately 96% token reduction while maintaining full functionality. It enables structured communication between AI models and context-providing services through a unified query language.
Preliminary Draft Positioning
The current publication target is a preliminary public draft of MCP-AQL.
This draft is intended to:
- Demonstrate protocol viability and real-world utility
- Show how semantic endpoint consolidation reduces token bloat
- Validate flexibility for modular integrations (security, execution, code/compute workflows)
This draft is not yet a final certification baseline. The repository now includes a fixture-driven conformance runner and semantic evaluation baseline, but broader ecosystem hardening is still in progress.
Endpoint Families
MCP-AQL supports semantic endpoint mode or a single unified endpoint. The standard semantic-endpoint profile extends traditional CRUD with an Execute endpoint, creating the CRUDE pattern:
| Endpoint | Safety | Description |
|---|---|---|
| Create | Non-destructive | Additive operations that create new state |
| Read | Read-only | Safe operations that query state |
| Update | Modifying | Operations that modify existing state |
| Delete | Destructive | Operations that remove state |
| Execute | Stateful | Runtime lifecycle operations (non-idempotent) |
Adapters MAY also define alternate semantic endpoint families when the target API is better represented by semantically explicit sets such as discover / query / manage / operate, database-oriented profiles like inspect / query / mutate / administer, or hardware-oriented profiles like discover / observe / control / maintain. Operations still retain standardized semantic categories for CREATE, READ, UPDATE, DELETE, and EXECUTE.
Examples of alternate semantic-endpoint profiles:
Extended CRUDE-style profile:
create / read / update / delete / execute / authorize
Alternative semantic profile:
discover / query / manage / operate
Token Efficiency
MCP-AQL dramatically reduces token consumption for LLM interactions.
Per-tool overhead: A typical MCP tool definition consumes ~500-700 tokens in context.
| Configuration | Tool Count | Token Cost | Reduction |
|---|---|---|---|
| Discrete Tools | ~30 tools | ~18,000 | Baseline |
| Discrete Tools | ~50 tools | ~30,000 | Baseline |
| Semantic Endpoint Mode (CRUDE profile) | 5 endpoints | ~4,300 | ~80-85% |
| Single Mode | 1 endpoint | ~1,000 | ~95%+ |
The savings scale with adapter complexity - the more operations your adapter supports, the greater the benefit of consolidation.
Key Features
- Unified Query Syntax - Consistent grammar for operations across all endpoints
- GraphQL-Style Introspection - On-demand operation discovery at runtime
- Schema-Driven Dispatch - Declarative operation definitions with automatic validation
- Flexible Parameter Resolution - Multiple sources checked for each parameter
- Batch Operations - Execute multiple operations in a single request
- Field Selection - Control response payload size for additional token savings
Quick Start
Discover Available Operations
{
operation: "introspect",
params: { query: "operations" }
}
Get Operation Details
{
operation: "introspect",
params: { query: "operations", name: "create_user" }
}
Execute an Operation
// Operations are adapter-specific - this example from a user management adapter
{
operation: "create_user",
params: {
email: "alice@example.com",
name: "Alice",
role: "admin"
}
}
Specification Documents
| Document | Description |
|---|---|
| Specification v1.0.0-draft | Current working draft |
| CRUDE Pattern | Standard semantic-endpoint profile |
| Endpoint Modes | CRUDE, semantic-endpoint, and single endpoint configuration |
| Introspection | Discovery system specification |
| Operations Guide | Operation design patterns |
| Collection Querying | Preferred query contract for list/search/query operations |
| Aggregations | Preferred summary/query shape for server-side aggregations |
| Computed Fields | Preferred _computed. convention for adapter-declared derived values |
| Relationship Queries | Preferred traversal contract for graph-style READ operations |
| MCP Server Discovery Bundle | Interrogation bundle contract for MCP-to-MCP-AQL generation |
| Cross-Domain Implementation Guide | Step-by-step guide for adapting MCP-AQL to databases, filesystems, API gateways, IoT, and other domains |
| Documentation Index | Full documentation structure |
| Changelog | Version history |
Reference Profile
DollhouseMCP serves as a practical reference profile for MCP-AQL.
It demonstrates the protocol in a large, production-oriented server, including security-loop integrations (Gatekeeper and Danger Zone). It is not the canonical definition of the protocol itself; normative behavior is defined by this repository's specification documents.
Conformance
Implementations claiming MCP-AQL conformance MUST:
- Implement the
introspectoperation for runtime discovery - Use semantic endpoint mode or single endpoint mode
- Return discriminated union responses (
{ success, data }or{ success, error }) - Document supported operations via introspection
Implementations SHOULD also pass the conformance test suite in tests/.
Status Note: This repository includes schema/example validation plus a fixture-driven conformance runner in
scripts/run-conformance-tests.mjs. The future packaged runner described indocs/conformance-testing.mdcan still grow beyond this baseline into direct live-adapter execution.
Contributing
We welcome contributions to the specification. Please see CONTRIBUTING.md for guidelines.
License
This repository uses split licensing:
- Specification text (docs): Creative Commons Attribution 4.0 International (CC BY 4.0). See
LICENSE-DOCS.- Applies to:
spec/docs/,spec/README.md, and other narrative documentation content.
- Applies to:
- Code and other software artifacts: GNU Affero General Public License v3.0 (AGPL-3.0). See
LICENSE.- Applies to:
spec/schemas/,spec/tests/, and any code/scripts included in this repository.
- Applies to:
For the authoritative path-based scope rules, see spec/LICENSING.md.
Commercial licenses are available for MCP-AQL software artifacts as an alternative to AGPL obligations. The specification text remains openly licensed under CC BY 4.0. See COMMERCIAL-LICENSE.md or contact licensing@mcpaql.org.
Acknowledgments
MCP-AQL builds upon the Model Context Protocol specification by Anthropic.
AQL MCP questions
How much can MCP-AQL reduce token usage?
It can provide approximately 96% token reduction by consolidating tools into semantic endpoint families.
What is the CRUDE pattern in MCP-AQL?
The CRUDE pattern extends traditional CRUD with an Execute endpoint, covering Create, Read, Update, Delete, and Execute operations.
Does MCP-AQL support discovering available operations at runtime?
Yes, it features GraphQL-style introspection for on-demand operation discovery.
What are the requirements for an implementation to claim MCP-AQL conformance?
Implementations must support the introspect operation, use semantic or single endpoint modes, return discriminated union responses, and document operations via introspection.