Client Integration

infrastrActure exposes one canonical integration endpoint:

GET /api/integrations/client?instanceId=<id>&userId=<optional-user>

This is the authoritative runtime config feed for clients.

Response Model

{
  "mcpServers": {
    "google-workspace": {
      "type": "streamable",
      "url": "http://host:13200/mcp"
    },
    "infrastrActure": {
      "type": "streamable",
      "url": "http://host:7500/mcp"
    }
  }
}

What Gets Merged

The endpoint merges:

user-specific installations
shared tools
running sandboxes
built-in infrastrActure MCP server

Tier-Aware Behavior

This is the most important integration rule.

Caller Key Tier	What It Gets
`standard`	user installs, standard shared tools, sandboxes
`admin`	everything in standard, plus admin shared tools and built-in `infrastrActure` MCP server

Normal users should never receive the shared GitHub admin server or the built-in infrastructure server through a standard sync path.

Shared Tool Reconciliation

Before shared-tool config is served, the service reconciles database state against Docker runtime state. That prevents dead or stale shared-tool entries from poisoning client bootstrap.

Multi-tenant key pattern

A client that serves both end users and operators (TessarAct is the canonical example) should hold two upstream keys and pick which one to use per call, based on the caller's privilege:

Caller path	Upstream key
end-user runtime sync	`INFRASTRACTURE_API_KEY_STANDARD`
operator / admin tooling	`INFRASTRACTURE_API_KEY_ADMIN`

The upstream key tier is the real security boundary. App-layer filtering inside the client is useful belt-and-braces, but secondary.

Push Notifications (Webhook)

Instead of relying solely on clients polling the integration endpoint, infrastrActure can push config-change events as soon as something changes.

See Push Notifications for the full contract.

Quick summary:

Variable	Purpose
`WEBHOOK_CLIENT_URL`	URL to POST events to
`WEBHOOK_CLIENT_SECRET`	Shared secret (`Authorization: Bearer`)

When set, the WebhookEmitter service fires on install, uninstall, and shared-tool state changes. Clients that implement the receiver can apply an incremental delta without a full re-fetch.

Connecting to the Built-in MCP Server

Only admin-tier clients should receive the built-in server entry:

{
  "infrastrActure": {
    "type": "streamable",
    "url": "https://mcp.aeromechindustries.com.au/mcp"
  }
}

That entry is used for management operations, not ordinary end-user runtime access.