Skip to main content
A connector is a source of tools: an MCP server, an OpenAPI or GraphQL API, or a Pipedream app. Workspace admins add connectors on Home with Add connector, beside the search, and manage each one by opening it: the Connection tab holds its settings, and Access decides who may use it through access policies. Creating and editing connectors is deliberately a web-UI action rather than one of Conduit’s built-in admin tools, because those requests carry upstream credentials — which don’t belong in an LLM’s tool-call transcript.

Connector kinds

Local connectors and CLI setup are hidden behind a browser-level rollout flag. The flag controls UI visibility, not server access. Remote MCP connectors are added by URL or from a standard MCP server.json manifest. OpenAPI and GraphQL connectors take the API base URL plus a spec — pasted in or fetched from a URL, with introspection doing the work for GraphQL; the stored spec’s freshness is shown on the connector and can be refetched on demand. Tools are namespaced by connector — a connector named github contributes github__create_issue — so two connectors can expose same-named tools without collision. What a client is shown is a shortened form of that name; see Connect AI Clients. Details that matter in production:
  • Stateful MCP servers work. Conduit maintains the upstream’s session across calls and transparently re-handshakes when the upstream expires it.
  • Live updates. Adding, changing, or removing a connector updates the tool lists of connected AI clients immediately, over the live MCP connection.
  • Adding a connector turns it on, allowed for no one: it opens on its Access tab to choose who can use it.
  • Turning a connector off, with Turn off… at the end of its tab bar, stops it for everyone whatever its grants say (a wildcard’s included), and keeps its settings, grants and people’s accounts for when it’s turned back on. Pipedream apps turn off the same way. Through the API, an UpdateConnector call that omits enabled leaves a connector as it was.
  • Deleting a connector (Remove connector, in its Connection tab) also deletes the credentials stored for it, including the grants each person connected.
Upstreams on private networks (a VPC-internal MCP server, a vendor API behind a private endpoint) need their hostname listed in CONDUIT_SAFEHTTP_ALLOWED_PRIVATE_HOSTS — see Network Access.

Authentication to the upstream

Each connector declares how Conduit authenticates to it. Independently of the method, the scope of the credential can be workspace (one shared credential an admin configures) or per-user (each user supplies or connects their own) — and that choice is what determines whose identity the upstream sees.

OAuth connectors

For MCP upstreams, Conduit discovers the upstream’s authorization server the standard MCP way and registers itself dynamically when the upstream supports it — zero configuration. The connector’s OAuth client choice is Conduit’s (registered this way) or Bring your own: when the upstream requires a pre-registered client, or you want people to approve your own app, supply its client ID and secret and register this callback URL with the upstream:
Each connector has its own callback URL, shown on its form — the form for a new connector shows it before you save, so it can be registered with the upstream first. Conduit registers it itself for a client it registers dynamically. Changing an existing connector’s client, either way, revokes people’s connected accounts: they were issued to the old client, so each person reconnects. If another admin changes connection settings while you’re saving, Conduit asks you to reload and retry. Reload before retrying: other connector fields may have saved before the OAuth client update was stopped. A failed initial OAuth setup removes an untouched connector, but keeps one another admin has already edited or configured. By default, Conduit requests every OAuth scope the upstream advertises, plus any scope the upstream’s first 401 response asks for that isn’t among them. Discovery refuses an authorization server whose metadata names a different issuer than the one the upstream points to. A sign-in response is refused before its code is used when it arrives on another connector’s callback URL, when it names another authorization server, or when it names none although the server advertised that it would (RFC 9207). For OpenAPI, GraphQL, and other non-MCP APIs there is no discovery document, so the admin also supplies the provider’s authorization and token endpoints. The client-credentials variant needs only the token endpoint — it has no authorization leg. Per-user OAuth grants (access and refresh tokens) are stored per user and refreshed automatically; users connect once and don’t re-authorize when a token expires. Each user can see and disconnect their own connections on the Accounts page.

Shared credential or their own: allow user override

When a workspace credential exists (a stored token, or a workspace OAuth grant), the connector’s allow_user_override setting (set through the API, UpdateConnector) controls whether that’s the only option:
  • Off — everyone’s calls use the workspace credential. One upstream identity, centrally rotated.
  • On — users may connect their own account or store their own token, which then takes precedence for their calls.
The setting exists because some services have no client an admin can register once on everyone’s behalf — each user or tenant instance must create their own (Salesforce and ServiceNow are the classic shapes). It’s meaningless for the client-credentials grant, which has no per-user form. With no workspace credential at all, the connector is per-user by definition: each user connects or supplies a token before the tools work for them. An AI client whose user hasn’t connected yet is guided through it in-band — see connecting accounts from the client.

Config fields: headers and environment variables

Beyond the credential, a connector can declare config fields — named values the connector injects on every use. On a remote connector each field is sent as an HTTP request header; on a local connector, as an environment variable for the spawned process. Each field declares:
  • a label and description for the form that collects it,
  • whether it is required,
  • whether it is secret (masked in the UI; values are write-only in the API regardless),
  • its scope: workspace (the admin stores one shared value) or user (each user supplies their own on the connect page, which shows exactly which host the value will be sent to before they type it).
Header names that could interfere with the protocol or impersonate the gateway’s own identity headers are rejected, including every name starting with Mcp-, which the MCP protocol reserves. A connector cannot override the headers Conduit itself sets (see the Pipedream identity headers for why that matters). One caveat specific to local connectors: a workspace-scoped value is, by design, delivered to the machine of every user who can use the connector — that is where the process runs. Anything that shouldn’t be shared that widely belongs in a user-scoped field. The admin UI states this on the form.

Where credentials live, and who can see them

  • Encrypted at rest. Every stored secret — tokens, header values, client secrets, OAuth grants — is encrypted (AES-256-GCM) with the instance encryption key. There is no external vault dependency.
  • Write-only in the API. No API response, admin tool, or export ever returns a stored secret — responses carry only “a value is set”. Editing a connector never requires re-entering values that aren’t changing.
  • Bound to where they are sent. A stored secret is kept on an edit only while its destination stays the same. Changing a connector’s URL needs the workspace token or auth headers re-entered, and changing an OAuth client’s client ID or token endpoint (or the URL, for client credentials) needs its client secret re-entered — otherwise the save is refused, so nobody can redirect a secret they can’t read. The exception is your own client in place of one Conduit registered: its secret was never shown, so a blank secret there means a public client. Changing the URL of an MCP connector that uses OAuth discovers its authorization server again for the new URL.
  • Clients never see upstream credentials. An AI client holds only its Conduit-issued token. Conduit attaches the upstream credential server-side on each call and never forwards the client’s bearer upstream — so a prompt, a transcript, or a compromised client can’t exfiltrate an upstream secret it never had. The one structural exception is local connectors, whose resolved values must reach the user’s own machine to start the process there.
You control the instance encryption key: supply your own via CONDUIT_ENCRYPTION_KEY, or let Conduit generate one in the data directory. The database plus your key is the vault. Credential use is observable even though credential values are not: every tool call is recorded in usage and the per-connector metrics, denied calls land in the audit log, and upstream failures surface in traces.