Model Context Protocol

The `aci-mcp` Server

Use this surface when an MCP client needs safe access to ACI Inference for shared-service update workflows. It uses stdio transport, exposes a narrow tool catalog by default, and can opt into admin mutations only when the host explicitly allows them.

Stdio transport

The shipped MCP server runs over standard input and output. Host tools spawn the process and exchange framed JSON-RPC messages.

Structured-task cloud starting point

When admin tools provision structured-task tenants, the current public default keeps memory opt-in.

Same inference contract

Every tool delegates to the same public inference client used by the CLI and Python integrations.

Narrow default tool set

Bind, adapt, constrain, infer, unbind, audit, consolidate, model listing, and tenant status are available without enabling admin mutation tools.

Opt-in admin mutations

Model registration and tenant create or delete tools remain disabled unless the host starts the server with admin enabled.

Start the server

The packaged entry points are `aci mcp serve`, `aci-mcp`, and `aci-inference-mcp`. They ship with the same `aci-engine` install as the CLI and SDK, and all use the same environment variables as the inference client and CLI.

export ACI_BASE_URL="http://127.0.0.1:8000"
export ACI_API_KEY="tenant-key"

aci-mcp
aci-inference-mcp

# equivalent
aci mcp serve --base-url "$ACI_BASE_URL" --api-key "$ACI_API_KEY"

# enable admin tools
ACI_MCP_ALLOW_ADMIN=1 aci-mcp

Host configuration

MCP clients should provide credentials through environment, not through tool arguments. The MCP process is an attachment layer on top of an existing ACI Inference service, not a standalone inference runtime. A typical host configuration looks like this:

{
  "mcpServers": {
    "aci": {
      "command": "aci-mcp",
      "env": {
        "ACI_BASE_URL": "http://127.0.0.1:8000",
        "ACI_API_KEY": "tenant-key"
      }
    }
  }
}

Default tool set

aci_bind

Bind supervised items into a tenant.

aci_adapt

Adapt a tenant from transition-style payloads.

aci_constrain

Apply a typed rule capsule.

aci_infer

Run inference against a tenant engine.

aci_unbind

Remove specific contributions by ID.

aci_audit

Audit a tenant engine.

aci_consolidate

Run consolidation.

aci_list_models

List models visible to the current API key.

aci_tenant_status

Inspect tenant readiness and counts.

Admin tool set

These tools are disabled unless the host starts the server with `--allow-admin` or sets `ACI_MCP_ALLOW_ADMIN=1`.

{
  "name": "aci_create_tenant",
  "arguments": {
    "model_id": "support-assistant",
    "tenant_id": "tenant-a",
    "namespace": "default",
    "target_dim": 4
  }
}

aci_register_model

aci_create_tenant

Create a tenant engine.

aci_delete_tenant

Delete a tenant engine.

Protocol flow

The server responds to `initialize`, `tools/list`, `tools/call`, and `ping`. Successful tool calls return text content containing JSON-serialized results.

// initialize
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"host","version":"1.0"}}}

// list tools
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// call a tool
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"aci_bind",
  "arguments":{
    "model_id":"support-assistant",
    "tenant_id":"tenant-a",
    "namespace":"default",
    "write_memory":false,
    "items":[
      {
        "id":"faq-1",
        "input":"Refunds require proof of purchase.",
        "target":{"label":"policy_refund"},
        "tags":["policy"]
      }
    ]
  }
}}

Tool schemas

The request schemas for `aci_bind`, `aci_adapt`, `aci_constrain`, `aci_infer`, `aci_unbind`, and `aci_consolidate` are generated from the same Pydantic request models used by the ACI Inference API.

{
  "name": "aci_infer",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["model_id", "tenant_id", "input"],
    "properties": {
      "model_id": {"type": "string"},
      "tenant_id": {"type": "string"},
      "namespace": {"type": "string", "default": "default"},
      "input": {"type": "string"},
      "use_memory": {"type": "boolean", "default": true}
    }
  }
}

Error behavior

Unsupported MCP methods return standard JSON-RPC errors. Inference client failures are returned as tool results with `isError: true` so hosts can treat them as tool-level failures rather than protocol failures.

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"error\":\"ACI Inference request failed with status 403.\",\"status_code\":403,\"detail\":{...}}"
      }
    ],
    "isError": true
  }
}

Safety boundary

Keep credentials in environment or host secret storage. Do not pass API keys inside tool arguments.
The MCP surface does not expose controller internals, runtime internals, signer material, or auth-registry internals.
Admin tools should only be enabled for trusted operator workflows.

Need the raw HTTP contract or the thin Python wrapper behind these tools? Use the API and SDK guides.

The documented MCP surface stays deliberately narrow and boundary-only. It belongs to `ACI Inference`, while `ACI Personal Agents` and `ACI Edge Runtime` remain direct SDK and runtime integrations.

API SDK All docs