Connectors and Private Routing

Operate

Connectors and Private Routing

Connectors are the governed private-connectivity surface. They do not make the gateway a connector marketplace or service mesh. They give approved MCP servers and selected API operations a registered route mode with health, lifecycle, impact, permissions, and metadata-only audit.

Audience

• Operators checking whether private backend traffic is allowed.
• Platform networking owners managing connector lifecycle state.
• Security reviewers verifying disabled or revoked routes block upstream traffic.
• Support engineers explaining a denied route without exposing backend details.

What is this?

This page covers direct private endpoint mode and outbound connector mode. Both modes require a registered target, approval state, allowed credential mode, safe route decision, and audit fields. The private-route decision contract records allow or deny, route mode, reason, whether upstream was attempted, and redaction status.

When do I use it?

Use it when an approved tool cannot reach a private backend, a connector is degraded, a route should be disabled during incident response, or a reviewer asks whether arbitrary private URLs can be proxied. They cannot.

What happens?

1. A governed call resolves an MCP server or selected API operation target.
2. The gateway evaluates registration, approval, policy, credential mode, host or route safety, connector lifecycle, and connector health.
3. The decision chooses direct_private_endpoint, outbound_connector, or denied.
4. Denied decisions set upstreamAttempted to false and emit safe route audit fields.
5. Connector impact can list affected MCP servers, routes, active-session counts, denied-route counts, and redaction status using safe IDs only.
6. Lifecycle mutations require backend-authoritative permissions.allowedActions[], expected_version, and a non-empty safe reason.

State and actions

State or field	Meaning for operators
approval_status	submitted, under_review, approved, or rejected; unapproved connectors cannot be treated as route-ready.
lifecycle_state	active, disabled, revoked, or archived; disabled is reversible, revoked is the stronger security action.
health.status	healthy, degraded, unhealthy, or unknown; degraded can still be route-available when the backend says so.
routeAvailable	Backend-computed route availability, not a UI guess.
allowedActions[]	The only lifecycle commands the UI or docs should present.

Supported lifecycle actions are view, impact, disable, reenable, revoke, and archive. Connector rotation, approval review, reject, and approve are not implemented for this slice and need source before public docs describe them.

What can go wrong?

• A public page exposes raw backend hosts, ports, trust bundle material, credential refs, request bodies, response bodies, prompts, or tokens.
• The UI renders a lifecycle command that is absent from permissions.allowedActions[].
• A caller retries an unhealthy, disabled, revoked, unregistered, unapproved, credential-denied, or host-policy-denied route instead of preserving the denial.
• A lifecycle request omits expected_version, races a newer connector version, or uses unsafe reason text.
• Docs imply arbitrary URL routing, a hosted connector platform, a service mesh dependency, or marketplace connectors. Those are outside V1.

Source truth

• contracts/jsonschema/connector.schema.json
• contracts/jsonschema/private-route-decision.schema.json
• contracts/events/audit-event.schema.json

Next

• Read Identity, Policy, Credentials for credential-mode failures.
• Read Sessions and Revocation when a connector action affects active sessions.
• Read Audit and Deny Diagnostics for safe denial explanation.