Connected System basics and kind

A Connected System registers one vendor or internal platform as a governed integration: authentication, roles, OpenAPI or MCP surface, and linkage to Business Entity manifests.

Why it matters

The Connected System is the trust boundary for a product. Certification, Enterprise MCP exposure, and Operational Trust rollups attach at system level before individual Business Entities go live for AI. One systemKey equals one integration folder under integration/<systemKey>/.

Prerequisites

Builder CLI installed and aifabrix auth status green
Sandbox systemKey chosen (lowercase, stable forever)
Quickstart: new Connected System or copied fixture

Where it lives

One Connected System folder holds the system contract and every Business Entity manifest — there is no separate data/ subdirectory.

Artifact	Path
System contract	`integration/<systemKey>/<systemKey>-system.json`
Application manifest	`integration/<systemKey>/application.yaml`
Business Entity manifests	`integration/<systemKey>/<systemKey>-datasource-*.json` (same folder)
Deploy bundle	`integration/<systemKey>/<systemKey>-deploy.json`
Secrets template	`integration/<systemKey>/env.template`

Manifest sections: system.basics, system.kind (type, optional systemKind).

Builder MCP


Manifest sections	`system.basics`, `system.kind`
UI tab	Overview (`?tab=overview`)
Help topics	`connectedSystemUi`, `section`, `goldenExamples`
Repair hooks	`rbac`, `expose` (list alignment via `repair`)

Post-upload handoff: Edit Connected Systems with Builder API.

How to set

Scaffold the folder:

aifabrix create <systemKey> --type external
cd integration/<systemKey>

Pick type — how the integration connects:

type	Use when
openapi	REST vendor with OpenAPI 3.x spec
mcp	Model Context Protocol tool server
custom	Patterns not covered by standard OpenAPI/MCP blocks

Edit <systemKey>-system.json — set root key, displayName, type, authentications[], and roles.
Align env.template — every secret uses kv:// references; never commit resolved tokens.
Add Business Entity JSON files in the same folder — one <systemKey>-datasource-*.json per entity; list each file in application.yaml. See Business Entities band.
Repair and validate:

aifabrix repair <systemKey> --rbac --expose --dry-run
aifabrix repair <systemKey> --rbac --expose
aifabrix validate <systemKey>

Optional systemKind — use only when the integration follows a platform pattern (for example a Role Assistant host or LLM system kind). Most vendor CRM and document integrations omit this field and rely on type alone.

Defaults and examples

Element	Purpose	Example
`key`	Stable integration identifier	`example-crm`
`displayName`	Operator-facing label	`Example CRM`
`type`	Connection model	`openapi`, `mcp`, or `custom`
`authentications[]`	Credential blocks	apikey or oauth2 method
`roles[]`	Business roles for RBAC	Admin, Reader, SalesManager

Example Connected System identity fragment:

{
  "key": "example-crm",
  "displayName": "Example CRM",
  "type": "openapi",
  "description": "Governed CRM integration for customer and deal entities",
  "authentications": [
    {
      "key": "default",
      "method": "apikey",
      "credential": {
        "security": {
          "apiKey": "kv://example-crm/apiKey"
        }
      }
    }
  ],
  "roles": [
    {
      "key": "Admin",
      "displayName": "Administrator",
      "permissions": ["external-system:manage"]
    }
  ]
}

Illustrative layout goals:

one systemKey folder equals one vendor boundary
every Business Entity JSON lists in application.yaml
auth secrets resolve through kv:// — never inline in committed JSON

Validate

aifabrix repair <systemKey> --dry-run
aifabrix validate <systemKey>
aifabrix test <systemKey>

Re-run validate after changing type, authentication method, or role keys — the compiler cross-checks Business Entity systemKey references and deploy bundle alignment on every pass.

Common mistakes

Mistake	Fix
Reusing `systemKey` after delete	Pick a new stable key
Auth secrets in `configuration[]`	Move to `authentications[]` credential `security` kv refs
Missing Business Entity files in `application.yaml`	Run `repair`

Limits

type and systemKind affect OpenAPI/MCP blocks but do not replace per-entity entityType on Business Entity JSON. One Connected System folder equals one vendor integration — split multi-product vendors into separate systemKey values when certification scope differs.

Documentation Index