MCP and Tools

Aura Bot Knowledge — indexed documents

AuraBoot exposes its commands and named queries as tools over the Model Context Protocol (MCP). External MCP clients (for example, desktop AI assistants, IDE agents, or other agent platforms) can connect to an AuraBoot deployment and call its tools with the same permission, validation, and audit guarantees as a logged-in user.

Concept

MCP is the inverse of internal tool selection. Internally, the AuraBoot agent runtime picks tools for its own LLM. Externally, MCP lets a foreign agent see AuraBoot's catalog and invoke a tool by name.

Two things make MCP tractable in AuraBoot:

Every command already carries input_schema, agent_hint, cmd_risk_level, and execution_config (which holds permissions).
The DSL Tool Provider turns those command definitions into tool descriptors automatically; external clients connect over the aura mcp serve CLI.

You do not write MCP tool code by hand. You author commands and let the provider expose them. Every published command that matches a model becomes a tool automatically — there is no exposeAsMcp switch to opt each one in or out.

When To Use

An external assistant (Claude Desktop, an IDE agent, another platform's agent) needs to call AuraBoot operations.
An internal team builds a separate agent stack but wants AuraBoot to be the system of record.
Long-lived integrations want a typed, schema-described contract instead of bespoke REST glue.

If the caller is itself an AuraBoot deployment, use ACP; MCP is for external clients.

Architecture

+--------------------+
|  External MCP      |
|  client            |
|  (Claude Desktop,  |
|   IDE agent, etc.) |
+----------+---------+
           | tools/list
           | tools/call
           v
+----------+-----------+        +-----------------------+
|  aura mcp serve CLI  | <----  |  DSL Tool Provider    |
|  (per deployment)    |        |  reads commands +     |
+----------+-----------+        |  named queries +      |
           |                    |  agent_hints          |
           |                    +-----------------------+
           v
+----------+-----------+
|  Command pipeline    |
|  (auth, permission,  |
|   validation, audit) |
+----------------------+

The MCP server is stateless per call. aura mcp serve requires the current session to have pinned a tenant (via aura login --tenant <name>), which maps the external client to an AuraBoot principal (a JWT subject carrying tenantId). From there, the call goes through the standard command pipeline.

DSL Tool Provider

Every published command that matches a model becomes a tool (the tool code is cmd:<commandCode>; named queries are nq:<queryCode>, and generic list:<modelCode> and get:<modelCode> tools are attached automatically):

{
  "code": "customer.query",
  "model_code": "crm_customer",
  "cmd_risk_level": "L0",
  "input_schema": {
    "type": "object",
    "properties": {
      "keyword": { "type": "string" },
      "status":  { "type": "string", "enum": ["active", "archived"] }
    }
  },
  "agent_hint": "Search customers by keyword and status.",
  "execution_config": {
    "permissions": ["crm.customer.read"]
  }
}

At discovery time (ToolDiscoveryContext supplies a modelHint), the DSL Tool Provider queries the ab_command_definition table, filtering by tenant_id, model_code, deleted_flag = FALSE, and is_current = TRUE. There is no exposeAsMcp field — every matching command is exposed. Each tool's schema comes from the command's input_schema (derived from execution_config.inputFields and model field metadata when absent).

Example: External Client Calling a Tool

A foreign MCP client over stdio or HTTP:

// tools/list response (excerpt)
{
  "tools": [
    {
      "name": "cmd:customer.query",
      "description": "Search customers by keyword and status.",
      "inputSchema": { "type": "object", "properties": { /* ... */ } }
    }
  ]
}

// tools/call request
{
  "name": "cmd:customer.query",
  "arguments": { "keyword": "acme", "status": "active" }
}

// tools/call response
{
  "content": [
    { "type": "text", "text": "Found 3 customers matching \"acme\" (active)." },
    { "type": "json", "json": { "rows": [ /* ... */ ], "total": 3 } }
  ]
}

Permissions and Audit

MCP is not a permission bypass:

The connecting client maps to an AuraBoot principal (a JWT carrying tenantId, obtained via aura login).
Every tool call resolves through <module>.<resource>.<action> permission codes.
Every call writes to ab_command_audit_log via POST /api/meta/audit/mcp-tool, with command_code set to mcp.<toolName> and phase_reached set to mcp_tool, sharing the same audit query UI as ordinary commands; it is also appended to a local ~/.aura/mcp-audit.log.
Risk-tier policies still apply; destructive tools may require an approval that the external client must resolve out-of-band.

Verify Checklist

The commands you want to expose are published and their model_code matches the target model (matching is automatic exposure; there is no switch).
Each exposed command has a strict input_schema and a precise agent_hint.
The external client has run aura login --tenant <name> and authenticates with an identity that has the required permissions.
Audit logs show command_code = mcp.<toolName> for external tool calls.
tools/list from the client returns only the tools the principal can actually run.