Configure OpenAPI and MCP operations

Bind vendor HTTP operations and optional MCP operation contracts to normalized capability keys on each Business Entity.

Prerequisites

• Vendor OpenAPI or MCP spec imported or authored
• Configure data flow operation keys defined
• System-level hints optional — Configure AI interfaces

Where it lives

Manifest keys: openapi, mcpContract (both root).

Builder MCP

Operation keys must match ^[a-z][a-zA-Z0-9]*$ and align with CIP openapiRef values. Concept depth: OpenAPI and MCP contracts.

How to set

1. Create or repair the entity scaffold:

aifabrix create <systemKey> --type external
aifabrix repair <systemKey> --expose --dry-run

2. Enable OpenAPI band and declare operations:

{
  "openapi": {
    "enabled": true,
    "operations": {
      "list": {
        "operationId": "listCustomers",
        "method": "GET",
        "path": "/customers",
        "permissions": ["external-system:read"]
      },
      "get": {
        "operationId": "getCustomer",
        "method": "GET",
        "path": "/customers/{id}",
        "permissions": ["external-system:read"]
      }
    },
    "documentKey": "example-customers"
  }
}

3. Keep keys aligned — list, get, create, update, upsert, delete or custom keys used in CIP and capabilities.
4. Add an mcpContract object when CIP filter.abac needs a datasource-scoped, mandatory policy readiness check — embed the MCP securityModel material (for example securityModel.tools, securityModel.abac) that the runtime persists on ExternalDataSource.mcpContract when published.
5. Repair exposure after operation changes:

aifabrix repair <systemKey> --expose
aifabrix validate <systemKey>

Defaults and examples

Example mcpContract fragment (when used) — mcpContract accepts any properties (additionalProperties: true); securityModel.tools / securityModel.abac is the documented pattern, not a fixed schema shape:

{
  "mcpContract": {
    "securityModel": {
      "tools": ["listCustomers"],
      "abac": ["external-system:read"]
    }
  }
}

Illustrative binding goals:

• entity openapi.operations is authoritative for CIP — not system-level hints alone
• permission arrays align with Configure roles and permissions
• renamed vendor operations update both operationId and CIP openapiRef

Bind a declarative upsert

upsert is a CIP operation shape, not an OpenAPI method. Its CIP definition
composes the datasource's standard create and update operations. Keep both
halves bound to their vendor operations, and declare the upsert capability with
shape: "upsert" in execution.cip.operations.

At execution time, CIP resolves existence once and checks permissions for the
selected create or update half. Denied access, missing identity, or ambiguous
identity stops the write; the operation does not fall back to the other half.
See Configure data flow
for the manifest fragment and identity rules.

Validate

aifabrix validate <systemKey>
aifabrix test-integration <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>

aifabrix validate <systemKey> catches broken operation references before runtime. Live proof follows CLI workflow. When operations change, re-run repair --expose so capability and RBAC bands stay aligned with HTTP bindings.

Common mistakes

Limits

This page covers operation binding shape — not full vendor OpenAPI import mechanics. Large specs may register subset operations only; align enabled keys with business capabilities actually exposed to AI. mcpContract is optional; REST-only integrations omit it entirely. After vendor API version bumps, re-import or hand-update operationId values together with CIP openapiRef bindings — partial updates fail at compile time with opaque ref errors.

An upsert declaration does not by itself certify every production transport.
Validate the actual platform connector, worker, REST, MCP, or Role Assistant
path used by the integration before publishing it for that channel.