Dollhouse Research Infrastructure and applied AI systems

MCP-AQL

MCP-AQL (Model Context Protocol - Agent Query Language) is the protocol layer that shrinks tool sprawl while keeping behavior explicit.

Instead of exposing dozens of separate tools, MCP-AQL groups operations into semantic endpoints and routes by operation.

Why Teams Use It

As MCP servers grow, classic discrete-tool setups become expensive in context tokens and harder to govern.

Mode Typical Registration Cost Why It Helps
Discrete tools (40-50+) ~30,000 tokens Full surface, high overhead
CRUDE (5 endpoints) ~4,300-4,500 tokens Clear safety grouping + lower overhead
Single endpoint (1 tool) ~1,100 tokens Minimal footprint for constrained contexts

MCP-AQL keeps the same underlying capabilities while reducing initial token load.

Classic MCP vs MCP-AQL

For engineers, the practical difference is call shape and discovery model.

Task Discrete-tool style MCP-AQL style
List personas tool: list_elements tool: mcp_aql_read + operation: list_elements
Create a persona tool: create_element tool: mcp_aql_create + operation: create_element
Execute an agent tool: execute_agent tool: mcp_aql_execute + operation: execute_agent
Discover capability surface docs + tool catalog runtime introspect

Example side-by-side:

{
  "tool": "list_elements",
  "arguments": {
    "type": "persona"
  }
}

{
  "tool": "mcp_aql_read",
  "arguments": {
    "operation": "list_elements",
    "element_type": "persona"
  }
}

Endpoint Model (CRUDE)

MCP-AQL extends CRUD with EXECUTE for runtime lifecycle operations.

Endpoint Intent Example Operations
CREATE Additive, non-destructive create_element, import_element, addEntry
READ Read-only queries list_elements, search, introspect
UPDATE Modify existing state edit_element, upgrade_element
DELETE Remove state delete_element, clear
EXECUTE Runtime lifecycle execute_agent, complete_execution, abort_execution

This endpoint classification is what enables safer host policies (for example: permissive READ, stricter DELETE and EXECUTE).

Introspection-First Discovery

Introspection is a core pattern in MCP-AQL, not an afterthought.

In plain terms: before a client calls a write or execute operation, it can ask the server what operations exist, which endpoint each uses, and what arguments are required.

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

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

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

This lets clients discover valid operations, parameters, and constraints at runtime instead of front-loading large static schemas.

That means:

Response Token Control

MCP-AQL supports field-constrained responses so clients can ask for only what they need.

Batch and Lifecycle Patterns

The protocol also supports multi-operation request batches and explicit execution lifecycle semantics.

Typical lifecycle flow:

  1. execute_agent
  2. record_execution_step (repeat as needed)
  3. get_execution_state or get_gathered_data
  4. complete_execution or abort_execution

This separation keeps runtime execution management explicit instead of hiding it inside generic update/delete calls.

What You Get In Practice

Default Path In DollhouseMCP

In DollhouseMCP, MCP-AQL is the default interface path. CRUDE mode is the default endpoint model.

Use single-endpoint mode when you need the smallest possible registration footprint.

Where It Lives