OpenAPI and MCP contracts

After upload, AI Fabrix publishes REST OpenAPI and Enterprise MCP surfaces from certified, exposed datasources — the contract layer for applications and AI clients.

Why it matters

Enterprise MCP packages business context and governed capabilities for AI. OpenAPI serves application integrators. Both must reflect published config on the dataplane — not draft local JSON in integration/<systemKey>/.

Contracts are how external apps and AI clients discover what they may request. They never expose raw vendor endpoints or credentials to models.

Prerequisites

Datasources with exposed.enabled and complete fieldMappings
Green validate and successful upload --probe
Governed capabilities understood before MCP testing

Where it lives

Layer	Config location	Role
System	`<systemKey>-system.json` `openapi` / `mcp`	Connectivity hints (server URL, auth flow)
Datasource	`externalSpec` on each datasource JSON	Authoritative vendor/API operation source per entity

System-level OpenAPI/MCP are hints; datasource externalSpec drives capability compilation.

How to set

Configure connectivity hints on system JSON — server URL, auth flow reference.
Set externalSpec per datasource — vendor OpenAPI operation source for compilation.
Enable exposure on Business Entities that should publish tools/routes — set exposed.schema, exposed.filterable, and root capabilities[]:

{
  "capabilities": [
    { "key": "get", "description": "Read customer", "riskLevel": "low" }
  ],
  "exposed": {
    "filterable": ["externalId", "country"],
    "schema": {
      "externalId": "metadata.externalId",
      "country": "metadata.country"
    }
  }
}

See Configure Enterprise MCP for the publish outcome operators verify after upload.

Repair expose flags and validate:

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

Verify online contract:

aifabrix show <systemKey> --online

Run E2E and certification pillars before production AI use.

Defaults and examples

Practice	Reason
Datasource `externalSpec` is authoritative	System OpenAPI is connectivity only
Enterprise capability keys on MCP	Auditors understand logs
`show --online` after every upload	Catches compiler drift
Explicit datasource selector when needed	Shared `resourceType` across files

Enterprise MCP tools map to enterprise capability keys — one tool per deduplicated business action (e.g. customer:search). Tool inputs use business metadata from fieldMappings, not vendor field names.

OpenAPI REST routes follow the same compiled capability model for application clients.

Validate

aifabrix show <systemKey> --online
aifabrix verify-trust <systemKey>
aifabrix test-e2e <systemKey>

Empty MCP tool lists usually mean datasources are not exposed or upload did not run — not MCP server outage.

Common mistakes

Mistake	Impact	Fix
Local JSON edited, no upload	Online contract stale	`upload --probe`
Datasources not exposed	Empty MCP tool list	`repair --expose`
Expecting vendor paths on MCP	Wrong mental model	Use enterprise capability keys
Skipping `show --online`	Debugging blind	Verify after every upload

Limits

Compiler output and online tool lists depend on upload environment and schema version — diff local exposed blocks against show --online when debugging missing tools.

This page does not duplicate full Enterprise MCP reference tables — see Enterprise MCP reference for selector inputs and advanced tool behavior.

Datasource root fields (key, displayName, systemKey, entityType, resourceType, primaryKey, externalId) must be valid before contracts compile — contract debugging often traces back to missing indexed externalId, not MCP configuration.

When multiple datasources share a resourceType, document the required MCP datasource selector in operator runbooks — silent defaults may route agent traffic to the wrong entity file.

REST OpenAPI routes published alongside MCP tools share compiled capability keys — clients must not assume vendor URL paths appear on the enterprise contract surface.

Contract diffs after upload should include both MCP tool lists and REST route tables when applications and agents consume the same integration.

Publish show --online snapshots in release notes when MCP tool counts change — agents cache tool metadata and may require refresh after contract updates.

Documentation Index