Integration Registration UI

Relevant source files

• apps/cloud/src/web/pages/create-org.tsx
• apps/cloud/src/web/pages/setup-mcp.tsx
• apps/host-selfhost/web/auth-layout.tsx
• apps/host-selfhost/web/setup.tsx
• e2e/scenarios/openapi-add-integration-action-bar.test.ts
• e2e/selfhost/mcp-oauth-reconnect-health.test.ts
• e2e/src/scenario.ts
• packages/core/sdk/src/client.ts
• packages/core/sdk/src/oauth-flow.test.ts
• packages/core/sdk/src/testing/oauth-test-server.ts
• packages/plugins/google/src/react/AddGoogleSource.tsx
• packages/plugins/graphql/src/react/AddGraphqlSource.tsx
• packages/plugins/mcp/src/react/AddMcpSource.tsx
• packages/plugins/microsoft/src/react/AddMicrosoftSource.tsx
• packages/plugins/openapi/src/react/AddOpenApiSource.tsx
• packages/react/src/components/accounts-section.tsx
• packages/react/src/components/add-account-modal.test.ts
• packages/react/src/components/add-account-modal.tsx
• packages/react/src/components/mcp-install-card.test.ts
• packages/react/src/components/mcp-install-card.tsx

The Integration Registration UI provides a progressive, detection-first experience for connecting external services (OpenAPI, MCP, GraphQL, etc.) to the Executor platform. These components handle the transition from a raw endpoint or specification to a registered Integration in the system catalog.

Architecture Overview

Registration components follow a "Probe-then-Register" pattern. Before persisting an integration, the UI typically analyzes the source to detect authentication requirements, metadata (titles/descriptions), and health check candidates.

Core Lifecycle

1. Detection: The UI probes the source (e.g., fetching an OpenAPI JSON or pinging an MCP SSE endpoint).
2. Analysis: Derives authentication templates and metadata from the probe result.
3. Refinement: The user adjusts the derived slug, displayName, and authMethods.
4. Registration: The Integration is created in the database.
5. Handoff: The user is routed to the Integration Detail hub to add specific Connections (accounts).

Component	Plugin	Key Features
AddOpenApiSource	OpenAPI	Spec parsing, Server URL selection, Auth derivation.
AddMcpSource	MCP	Transport selection (Stdio/Remote), Probe state machine.
AddGraphqlSource	GraphQL	Header/Query API Key configuration.
AddGoogleSource	Google	Product bundling (Discovery Doc aggregation).

Sources: packages/plugins/openapi/src/react/AddOpenApiSource.tsx85-90 packages/plugins/mcp/src/react/AddMcpSource.tsx43-49 packages/plugins/graphql/src/react/AddGraphqlSource.tsx31-35

---

OpenAPI Registration Flow

The AddOpenApiSource component manages the registration of RESTful services via OpenAPI specifications.

Detection and Analysis

When a URL or JSON blob is provided, the component triggers a preview via the previewOpenApiSpec atom packages/plugins/openapi/src/react/AddOpenApiSource.tsx127

• Server Selection: If multiple servers are defined in the spec, the user can choose the baseUrl packages/plugins/openapi/src/react/AddOpenApiSource.tsx150-156
• Auth Derivation: Authentication templates are automatically extracted from the spec's securitySchemes packages/plugins/openapi/src/react/AddOpenApiSource.tsx50

Slug Collision Guard

To prevent clobbering existing integrations, the UI uses the useSlugAlreadyExists hook. If the derived or typed slug is already in use by the tenant, a SlugCollisionAlert is displayed and the "Add" button is disabled packages/plugins/openapi/src/react/AddOpenApiSource.tsx35-37 packages/plugins/openapi/src/react/AddOpenApiSource.tsx210-212

Logic Flow: OpenAPI Registration

Title: OpenAPI Registration Sequence

Sources: packages/plugins/openapi/src/react/AddOpenApiSource.tsx99-130 packages/plugins/openapi/src/react/AddOpenApiSource.tsx147-173

---

MCP Probe State Machine

Registration of Model Context Protocol (MCP) servers supports two transports: stdio (local processes) and remote (SSE/HTTP). Remote registration uses a formal state machine to handle the asynchronous probing of the endpoint.

Probe State Machine

The AddMcpSource component utilizes a reducer to manage the connection lifecycle packages/plugins/mcp/src/react/AddMcpSource.tsx112-158:

State	Transition Trigger	Description
url	set-url	Initial input state.
probing	probe-start	Actively pinging the MCP endpoint.
probed	probe-ok	Success; metadata and auth requirements retrieved.
error	probe-fail	Connection failed; displays error and allow retry.
adding	add-start	Persisting the MCP integration to the catalog.

Stdio Transport

For local hosts (CLI/Desktop), the UI allows configuring stdio commands. It uses integrationDisplayNameFromStdio to derive a name from the command string (e.g., npx arguments) packages/plugins/mcp/src/react/AddMcpSource.tsx183-194

Sources: packages/plugins/mcp/src/react/AddMcpSource.tsx89-108 packages/plugins/mcp/src/react/AddMcpSource.tsx179-182

---

Authentication Method Editor

The AuthMethodListEditor is a shared component used across all registration flows to define how connections to the integration should be authenticated.

Editor Data Flow

1. Seeding: Components like AddOpenApiSource seed the list with detected methods (e.g., OAuth2, ApiKey) packages/plugins/openapi/src/react/AddOpenApiSource.tsx191-200
2. Modification: Users can add "Custom" methods or delete detected ones packages/react/src/components/add-account-modal.test.ts183-192
3. Wire Format: Upon submission, the editor's internal AuthMethodRow state is converted to the authenticationTemplate wire format expected by the API packages/plugins/openapi/src/react/AddOpenApiSource.tsx40-43 packages/plugins/graphql/src/react/AddGraphqlSource.tsx63-71

Supported Kinds

• none: No authentication required.
• apikey: Header or Query parameter based keys.
• oauth: Full OAuth2 flow (Authorization Code/Client Credentials).

Sources: packages/react/src/components/auth-method-list-editor.tsx21-25 packages/plugins/graphql/src/react/AddGraphqlSource.tsx143-148

---

Health Check Selection

Integrations can define a "Health Check" to verify connection validity. During registration, specifically in the OpenAPI flow, users can select a candidate operation to serve as the health probe.

Health Check Candidates

The HealthCheckConfigFields component allows users to:

1. Select an operation from the spec (e.g., GET /user) packages/plugins/openapi/src/react/AddOpenApiSource.tsx123
2. Define hcIdentityField: A JSONPath-like string used to extract a displayable identity (e.g., email) from the health check response packages/plugins/openapi/src/react/AddOpenApiSource.tsx124 packages/react/src/components/accounts-section.tsx90-95
3. Set static arguments (hcArgs) required for the probe packages/plugins/openapi/src/react/AddOpenApiSource.tsx125

Sources: packages/plugins/openapi/src/react/AddOpenApiSource.tsx19-20 packages/react/src/components/accounts-section.tsx85-87

---

Code Mapping: UI to Core Entities

Title: UI Component to Core SDK Mapping

Key Functions and Hooks

• useIntegrationIdentity: Manages the synchronized state between the integration's display name and its URL-safe slug packages/react/src/plugins/integration-identity.ts26
• slugifyNamespace: Utility to transform human-readable strings into valid IntegrationSlug formats packages/react/src/plugins/integration-identity.ts15
• createCredentialPayloadOrigin: Determines if a credential should be stored as a raw value or linked to a provider like 1Password packages/react/src/components/add-account-modal.tsx139-159

Sources: packages/plugins/openapi/src/react/AddOpenApiSource.tsx110-113 packages/react/src/components/add-account-modal.tsx125-128