Connector foundations: code, quality checks and OAuth

The workshop prepares and checks connections to external services. This page describes stage 4 capabilities. Availability on an installation depends on a completed rollout and explicit operator configuration. Ready-made service cards, concrete bridges and any migration of the existing ERP integration are separate work.

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.

Connector code runs in a separate service rather than the platform process. Workshop authors cannot upload executable code, set the service access header or change gateway 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 content. 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 credentials, 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.

Quality checks and description suggestions require the existing do permission. View permission 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 choices of 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. Advertised client metadata document support selects CIMD: 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 selected from the external metadata 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 remains another setup method. Manual setup and the explicit DCR command are retained. A failure after selecting CIMD never silently starts DCR registration. 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 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.

Operator configuration

Ordinary workshop authors cannot change these variables. Empty configuration keeps new capabilities closed and preserves saved MANUAL/DCR connections.

Variable	Purpose
`CONNECTORS_CODE_SERVICES_JSON`	Exact approved services, releases and HTTPS URLs with separate gateway keys. Defaults to an empty list.
`CONNECTORS_OAUTH_PUBLIC_ORIGIN`	Public platform HTTPS origin without a path. Empty by default and never derived from request headers.
`CONNECTORS_AI_PROVIDER_ID`, `CONNECTORS_AI_MODEL_ID`	Exact approved model with structured output support and system credentials. Unset by default.
`CONNECTORS_AI_ACCOUNTING_PORTAL_ID`	Existing Bitrix24 account to which system model usage is attributed. The author's wallet is not charged.
`CONNECTORS_AI_MAX_CONCURRENT`	Zero to two shared slots for checks and description suggestions. Zero disables calls.
`CONNECTORS_AI_TIMEOUT_MS`	Per-model-call budget: 10 seconds by default and no more than 30 seconds.

A quality run makes at most 20 model calls; a description suggestion makes one. Each call uses a single attempt without a paid fallback and a maximum output of 1024 tokens. A complete quality run has a 30-second deadline. Ending the caller's wait does not release its slot until the underlying model request settles. After a crash, occupied slots are not automatically reassigned: operator recovery requires proof that the previous request stopped.

Compatible activation and rollback

Apply the additive migrations while keeping the service list, public origin and model configuration empty. Verify that there are no new CODE or CIMD rows.
Install the tested stage 4 build on every serving process and both deployment slots. The exact build commit SHA is recorded in final merge request !4975 with its verification. Keep configuration empty throughout the update.
After verifying the process inventory, configure approved services and/or the public origin separately. Model activation requires its own explicit configuration.
Once CODE or CIMD rows exist, roll back only to a tested build that understands these kinds and records. Disabling a flag or connector does not make an older build compatible. Retain additive tables and public documents; do not reverse the migrations or convert new rows to legacy kinds.

The service template, sample adapter and automated checks use synthetic data. They do not start a real integration or activate production configuration.