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

Layer	Location
OpenAPI ops	`<datasourceKey>.json` → `openapi.operations`
MCP ops	`mcp` block on same file (when entity exposes MCP)
Authoritative vendor spec	`externalSpec` / imported document key
UI	Business Entity Operations tab (`?tab=openapi`)

Manifest sections: datasource.openapiOperations, datasource.mcpOperations.

Builder MCP


Manifest sections	`datasource.openapiOperations`, `datasource.mcpOperations`
UI tab	Operations (`?tab=openapi`)
Help topics	`section`, `schemaCatalog`, `dependencyGraph`
Repair hooks	`expose`, `rbac`

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

Create or repair the entity scaffold:

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

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"
  }
}

Keep keys aligned — list, get, create, update, delete or custom keys used in CIP and capabilities.
Add MCP operations when the entity exposes MCP tools — mirror capability keys on the same file.
Repair exposure after operation changes:

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

Defaults and examples

Element	Purpose	Example
Operation key	CIP and capability binding	`list`, `get`, `create`
`operationId`	Vendor OpenAPI id	From imported spec
`method` / `path`	HTTP binding	`GET` + `/customers`
`documentKey`	Spec registry key	Matches imported document

Example MCP band fragment (when used):

{
  "mcp": {
    "enabled": true,
    "operations": {
      "read": {
        "toolName": "example_crm_list_customers",
        "description": "List customers scoped by ABAC"
      }
    }
  }
}

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

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

Mistake	Fix
System OpenAPI as only contract	Entity `openapi.operations` is authoritative for CIP
Operation id mismatch with CIP	Align `openapiRef` and operation keys
MCP ops without AI contract	Configure AI contract
Invalid operation key casing	Use camelCase starting with lowercase letter
Permissions not in RBAC	Map roles before upload

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. MCP entity bands are optional; REST-only integrations omit mcp 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.

Documentation Index