Connector Administration¶

Mission Control registers MCP servers and governs each discovered tool as a separate Connector. The current release supports only stateless MCP Streamable HTTP revision 2026-07-28, with none, bearer, one custom header, multiple static headers, shared oauth, and the two per-user modes per_user_oauth and per_user_headers. It does not negotiate or fall back to initialize-based servers. Use the shared OAuth guide for the company grant's Connect/Reconnect/Disconnect and refresh, and Per-user connectors for Connectors that act as the calling person; delegated token exchange is not included in the current release.

Register a server¶

Prerequisite: organization.settings.manage at organization scope, granted by organization.owner and organization.admin, plus write access to the reviewed organization YAML and gateway environment.

Add the server to organization YAML with a stable lowercase ID, display name, URL, timeout, authentication, and enabled state.
Begin with tools: [] for a new server.
Set any referenced credential in the gateway environment and restart the gateway.
Have the operator validate the files and restart gateway and Console.
Open Connectors and select the server.

The server detail shows the configured endpoint, transport, authentication type and gateway-reported resolved state, plus current diagnostic health and checked time.

For a service that needs more than one upstream header, use this copyable shape:

auth:
  type: headers
  headers:
    Authorization:
      credential: env/CRM_AUTHORIZATION
    X-Tenant-ID:
      value: example-team

CRM_AUTHORIZATION contains the complete value, such as Bearer synthetic-credential; this mode does not add a scheme. A credential is resolved from the gateway environment during startup preparation. A value is literal non-secret configuration: even text such as env/ORDINARY_TEXT stays literal and is visible in redacted configuration. Each entry must contain exactly one of those fields. Authorization must use credential.

Header names are compared without case and stored in lowercase. Configure 1–32 unique names, each at most 128 ASCII letters, digits, or hyphens. Each value is at most 8192 UTF-8 bytes, all encoded headers together are at most 32 KiB, and CR/LF is rejected. Values may contain horizontal tab, printable ASCII, and characters from U+0080 through U+00FF; NUL, other control characters, DEL, and characters above U+00FF fail validation because the Fetch transport cannot send them safely. Routing, framing, proxy, browser security, MCP protocol, Trace, baggage, and Mission Control internal headers are reserved. This reserved-name check now also applies to the older singular header mode; migrate a rejected singular name to an ordinary provider-supported name such as X-API-Key.

Per-user connectors¶

A per-user Connector acts as the person calling it. Instead of one company credential, each person connects their own account under My connections, and every tool call on the Connector runs with that person's credential and nothing else. Choose it for services whose records and permissions belong to individual people.

Two modes exist:

per_user_oauth — each person completes their own OAuth authorization-code sign-in at the upstream service through the Console. The client registration, scopes and allowed origins are configured once for the Connector; the grants belong to the people.
per_user_headers — each person saves a value for every declared header name, for example a personal API token. Values are encrypted with the gateway's Connector keyring and never displayed again.

Both modes require a static discoveryAuth (none, bearer, header, or headers). It is used only by Refresh connection, which need a credential before anyone connected; it is structurally unavailable to tool calls, so a person without a connection is never served with it. See Organization YAML for both shapes.

The server detail page shows a mode card with the discovery credential, the declared header names, and N people connected: the number of live personal grants on the current credential generation or of stored header sets. Administrators never see whose grant, a token, or a header value. There is no Connect for the company on a per-user Connector; connecting is each person's own act.

A person may connect through an allowed ordinary user key, an active Team with own-key creation permission and a permitted draft tool policy, or an available Chat deployment with a saved Person's connection requirement. This last consumer path requires no Team membership. When that access ends, their grant stays but shows as Orphaned on My connections and is not used; restoring access reactivates it without a new sign-in. A tool call without a usable personal credential is answered in band with a connect request that names the Connector and links to My connections; nothing is dispatched. See Gateway errors.

A managed deployment uses a person's grant only for its saved per-Connector Person's connection requirement and the actual initiating person. Company connection binds the exact configured Connector. There is no global switch or fixed-person/customer-label fallback. Request evidence records the actual credential owner.

The Console reaches the gateway through signed control routes that act as the person, need no administrator permission, and return no credential material:

Method and route	Result
`GET /internal/connectors/user-connections`	The person's per-user Connectors with status, header names and expiry.
`POST /internal/connectors/{serverId}/user-auth/start`	Authorization URL for the person's own sign-in.
`GET /internal/connectors/{serverId}/user-auth/status`	Safe status of the person's own grant.
`POST /internal/connectors/{serverId}/user-auth/complete`	Signed code/state/optional issuer body; 204 after a verified completion.
`POST /internal/connectors/{serverId}/user-auth/disconnect`	204 after the person's grant, tokens and pending flows are removed.
`PUT /internal/connectors/{serverId}/user-headers`	Stores the person's values for exactly the declared names; 204.
`DELETE /internal/connectors/{serverId}/user-headers`	Removes the person's values; 204.

Connection states¶

Every server carries one of five connection states, on the Connectors list and on its page, derived from the latest health check of any kind:

State	Meaning
Healthy	The latest check succeeded; the detail shows its latency.
Unstable	The latest check failed for a reason other than authorization; the detail shows the safe error category and how many checks in a row have failed, and the page says when the server was last healthy.
Needs authorization	The latest check failed because the credential was refused or missing (`connector_auth_required`, `connector_auth_failed`, `connector_insufficient_scope`). Reconnect the shared grant or correct the credential reference.
Disabled	The server is `enabled: false` in YAML; nothing is checked and no tool is eligible.
Not tested	No check has run yet.

The state is separate from the OAuth grant status on the same page: a connected grant with a failing server is Unstable, and a missing grant shows as Needs authorization once a check has tried it. The page also says when the last check ran and whether the schedule or an administrator ran it.

Scheduled health and discovery¶

The gateway owns one bounded, non-overlapping Refresh connection operation for enabled MCP servers. It starts asynchronously after startup and repeats every MCP_DISCOVERY_INTERVAL_SECONDS (default 300 seconds); 0 disables scheduled refresh. MCP_HEALTH_INTERVAL_SECONDS is rejected with a migration diagnostic: remove it and configure the unified interval. Console reads results and runs no separate schedule.

Scheduled runs use configured shared/discovery credentials, never use a person's grant, never start a sign-in and never execute a business tool. A failed refresh records a safe category and checked time without erasing the last successful tool schemas. Repeated identical discovery confirms the existing result; manual refresh retains audit evidence.

Cached schemas survive an unchanged restart only when organization/server, endpoint, transport, protocol and discovery-auth identity match the derived non-secret target key. A changed target or old unkeyed discovery cannot reuse unrelated schemas. Missing schemas require a successful refresh before tool use; schema drift, undeclared or missing tools remain unavailable.

Test connectivity¶

Select Refresh connection to check connectivity and refresh schemas together. Mission Control sends pinned 2026-07-28 stateless server/discover and tools/list requests with prepared server headers. It never forwards the administrator's inbound credential. Credential-bearing requests reject redirects, so another origin receives no custom header. No initialize fallback or protocol session is created.

The result includes status, latency, safe error category and checked time. Health is diagnostic: a previous failure cannot block model routing, MCP tool listing or invocation when configuration, credentials, matching schemas, Team allowance, key policy, rules and approvals permit the operation. Historical checks remain evidence and do not become current-process results after restart. Model deployments retain their separate manual non-inference Test connection action.

A refresh does not declare, classify or enable tools. OAuth authorization may still be needed independently; upstream failure never blocks gateway startup or readiness.

Next: approve and enable tools¶

Continue with Discover and govern Connector tools for discovery, declarations, classifications, automatic execution, tool sets, argument/result rules, and invocation history.