Connector foundations: code, quality checks and OAuth

The workshop helps you prepare and check a connection to an external service. Its capabilities on a given installation depend on a completed update and explicit operator configuration. The availability of a particular external service depends on its installed adapter.

Connector kinds

Kind	Where tools come from
Declarative	The author describes HTTP requests in a connector version. OpenAPI import creates drafts for further review.
MCP	The author retrieves tools from an external server using the Model Context Protocol (MCP), selects the required ones and saves a version snapshot.
Code	The author selects a prepared service and release. The service declares its tools over MCP, and the author selects them for the version.
BRIDGE	A service declares immutable tools and persists long-running operations. The workshop uses its approved snapshot.

Connector code runs in a separate service rather than in the platform process. Workshop authors cannot upload executable code, set the service access header or change the service keys. The service URL, service identifier and release identifier must exactly match the operator configuration.

Code connector creation is available only after operator configuration. A saved URL alone does not enable it. Retrieved tools pass the common schema, access, limit and write-policy checks. Publication still requires the mandatory checks through a matching sandbox.

How the service receives credentials

The gateway passes only the data required by the chosen authentication method: declared key fields, a username and password, or a current OAuth access token. It does not pass an OAuth client secret, refresh token or vault envelope.

Data travels over HTTPS to the pinned release URL. Tool-list requests carry no connection credentials. The service separately checks the gateway key and release, keeps credentials in the current call context only and does not log them. Responses and debug data are scrubbed of supplied secrets.

A rejected gateway key does not mean the employee must sign in to the external service again. Automatic token refresh is allowed only for a read call when the service separately reports, before execution, that the connection credentials were rejected. A write call is never automatically replayed after that response: doing so could change external data twice.

Additional quality checks

The workshop accepts five to ten synthetic requests for a quality check. A model selects a tool and arguments, the platform validates them against the schema, and the model evaluates the match with the description. No actual external-service tools run during this check.

Run the additional check in the version editor after separately saving the current tool descriptions. The mandatory checks tab only displays a saved report.

The result is advisory: pass, mismatches or unavailable. It does not replace mandatory checks, mark a version ready or authorize publication. It describes model behavior on the supplied synthetic examples, not the quality of real external-service data.

A report belongs to a specific version and tool content. Editing a draft clears its report; a late response cannot attach to the changed version. Reopening displays only a matching validated report. Connection secrets, sandbox data, employee logs and real tool responses are excluded from model input.

A suggested description is first shown as a preview. Applying it updates the local unsaved draft; saving remains a separate author action. A late suggestion received after a draft edit is not applied.

Additional quality checks and description suggestions require the Write access level. The Read level allows reading a saved report. No model is configured by default, so these actions are unavailable. There are no background runs, paid fallback routes or automatic switching to another model.

Automatic OAuth setup for MCP

A saved OAuth client takes precedence. Newly advertised registration capabilities do not convert existing connections to another method.

When no client is configured, the platform reads resource and authorization-server metadata. If the server advertises client metadata document support, CIMD is selected: the client identifier becomes the HTTPS URL of an immutable platform document. This method requires explicit support for a public client without a shared secret and Proof Key for Code Exchange (PKCE) with S256. It also works without a dynamic registration endpoint.

Scopes returned by the external service are saved with the client configuration and must be a subset of the version’s approved scopes. An empty selection remains empty; starting authorization never replaces it with the broader authored list. A change of version or authentication requires explicit setup again.

When CIMD is not advertised, available dynamic client registration (DCR) remains another setup method. Manual setup and the explicit DCR command are retained. A failure after selecting CIMD never silently starts DCR. Automatic registration commands are not provided for code connectors.

With CIMD, the client identifier is read-only and there is no client secret. The redirect URL is pinned in the client document. Resource, authorization server, client and redirect parameters are sealed into the one-time authorization state. If they change, the code is not exchanged for tokens under the new settings: authorization must restart.

Changing the OAuth application or public origin requires explicit setup and, when replacing an active binding, confirmation of reauthorization. Old public documents are never rewritten and survive disabling, retirement or deletion of the connector. Document availability grants no right to execute tools.

One metadata setup sequence allows at most seven network requests within 30 seconds, with at most 10 seconds per request and 64 KiB per response. Redirects and private destinations are denied. Documents must use a JSON media type and valid UTF-8. This implementation targets MCP Authorization 2025-11-25 and CIMD draft-00; it does not claim universal OAuth interoperability.

BRIDGE workshop and sandbox

BRIDGE creation is offered only when the operator has configured an approved service and the author has permission to perform workshop actions. If capability discovery fails, creation remains unavailable. Enter the exact service ID, release ID, HTTPS URL and allowed hosts, then configure authentication, connection parameters and limits. Gateway keys belong to the operator and are never entered here.

Discovery retrieves the adapter's approved tool declarations. Names, descriptions, schemas and READ and WRITE annotations are read-only. Manual tools, overrides and WRITE downgrades are unavailable, including through the JSON editor. Quality checks use the saved approved snapshot. Description suggestions are advisory: changing a declaration requires a new adapter release and rediscovery. Publication uses the existing checks and read-only probe calls through the matching sandbox.

A sandbox call may not return its result immediately: the workshop shows a waiting state and a result button. Automatic polling respects the delay set by the server. Closing the workshop stops polling without cancelling the job. BRIDGE results are normalized; transport debug data and credentials are not displayed. Sandbox calls are free and use the initiating operator's session, separate from application or Cowork keys.

Running a tool in the sandbox and viewing its result require the Write access level. A write tool runs only after explicit confirmation. Only the user who started the call can see its result, and only under the current sandbox authorization. Reconnecting, deleting the sandbox or losing access hides old results: the neutral code CONNECTOR_OPERATION_NOT_FOUND is returned instead. These actions are performed in your account and are not part of the V1 API for application keys.

Operator preparation

The installation operator enables BRIDGE creation after preparing a verified HTTPS service, an exact approved release, gateway key rotation and durable job storage. Service keys and deployment configuration are never part of public tool declarations. The bundled adapter is a test sample, not a production ERP bridge.