Connectors reference
Provider support
Provider credentials and an MCP server are separate parts of the setup. A stored credential alone does not provide MCP tools; the runtime also needs a supported provider server or an endpoint binding.
There are two ways to reach many applications:
- Custom app (native OAuth). Any application whose MCP server or API follows OAuth, such as Linear, Notion, or Stripe, connects directly. Introspection discovers its endpoints and obtains an OAuth client, and each application is its own connector.
- Pipedream. One connector reaches the applications in Pipedream’s catalogue through Pipedream Connect. Each authorized application adds its own MCP endpoint.
Slack and Google services have dedicated templates. The dashboard offers these
four connector types, and the provider slug is what the platform keys
provider-specific behavior on.
| Connector type | provider | Outgoing access | Inbound connector events | Requires a runtime at authorization |
|---|---|---|---|---|
| Slack | slack | Recipe channel tools using the Slack Bot API. | Slack messages can start or continue tasks. | Yes |
| Google services | google | Stored OAuth credential for the Gmail, Calendar, and Drive APIs. | No. | No |
| Pipedream | pipedream | One connector for many applications. Each authorization adds an MCP endpoint for the selected runtime whose server ID is the application slug. | No. | Yes |
| Custom app | Derived from the connector name, such as notion or linear | Any OAuth-protected MCP server or API, such as Linear, Notion, or Stripe, configured through OAuth discovery or explicit OAuth settings. | No generic inbound route. | Only when the authorization includes a binding |
The dashboard finds custom apps by searching the open MCP
registry by name; selecting a listing fills in the application’s MCP server URL
and runs OAuth discovery on it. You can also enter an MCP
server or issuer URL directly. The REST registry search is
GET /v1/connectors/custom/apps with a required q of at least two characters
and an optional limit; it needs no existing connector. A Pipedream connector
has its own application catalogue at GET /v1/connectors/{connector_id}/apps.
A custom app’s provider is derived from its name, so a custom app named
Linear gets linear. That lets a Recipe’s linear connector requirement find
it, and its MCP server is suggested for the binding. It is still a custom app:
it needs a runtime only when the authorization includes a binding. The names
slack and pipedream are reserved for the built-in integrations and cannot
be used for a custom app.
Pipedream works the other way round. Its provider is always pipedream, and
the application sits on each connection as provider_app, so a Pipedream
connection to Linear is not a linear connector.
The templates prefill OAuth endpoints, scopes, and API hosts. CLI and REST
create calls must supply those settings or use issuer discovery; selecting a
provider slug does not copy a template. Any slug other than the ones above is a
label for a generic connector. The Google slugs (google, gmail,
google_calendar, google_drive) additionally request offline access during
authorization so that Google returns a refresh token. Read
connector.requires_runtime before authorization. A runtime requirement does
not by itself mean that a provider supports incoming events.
Operator in Slack provides the separate setup for an organization Slack installation and Operator conversations.
Authentication modes
Set auth_mode when creating the connector. The CLI uses hyphenated values
such as oauth-stored; REST fields use snake case such as oauth_stored.
| REST value | How authorization works | Current support |
|---|---|---|
static | Register a provider key you already hold. | The token broker serves the stored credential. |
oauth_stored | Authorize with OAuth and store the resulting account credential. | The token broker serves a usable stored credential. |
client_credentials | Authenticate a Pipedream Connect project with its client ID and secret. | Pipedream account authorization. The public stored-token broker does not serve this mode. |
identity_assertion | Mint a signed identity assertion from the connector’s linked application. | Requires a configured application, audience, and usable signing key. |
person_authorized | Release a stored credential only for a request covered by an approved mission. | Returns a pending mission when approval is required. |
federated_exchange | Exchange an identity token with a federated issuer. | Accepted as a mode, but the token broker does not serve it. |
An endpoint that links a connector cannot also configure an authorized
application or a stored Authorization header. Other stored headers can still
be used. See endpoint authentication.
OAuth discovery
A custom app needs the provider’s authorization and token endpoints and an OAuth
client. Introspection can discover both. Supply issuer when creating the
connector, or --issuer in the CLI.
Where discovery starts
| You supply | What Introspection reads |
|---|---|
| A listing picked from the MCP registry (dashboard) | The listing’s MCP server URL, handled as below. |
| The MCP server URL | The server’s protected resource metadata (/.well-known/oauth-protected-resource, RFC 9728), which names its authorization server. The server’s host becomes the default allowed API host. |
| The authorization server’s issuer URL | Its OAuth authorization server metadata (RFC 8414) or OpenID Connect discovery document. |
authorization_endpoint and token_endpoint | Nothing. Discovery is skipped, and you supply the client and scopes yourself. |
When an MCP server publishes no protected resource metadata, Introspection treats the URL you supplied as the issuer.
How the OAuth client is obtained
Introspection tries these in order when client_id is omitted:
| Provider configuration | Result |
|---|---|
| Client ID metadata documents are supported. | Introspection uses its published client metadata URL as the client ID. No client secret is needed. |
| Dynamic client registration (RFC 7591) is advertised. | Introspection registers a client with the provider. |
| Neither is available. | Supply the provider’s client_id at connector creation. |
With a client you supply, pass client_secret when the token endpoint requires
one. A public client with no secret must be accepted by the provider, which must
also advertise PKCE S256 support.
The CLI accepts --client-id, --client-secret, --authorization-endpoint,
and --token-endpoint on create. client_id and the OAuth endpoint URLs cannot
be changed through connector update. A stored client secret can be replaced. When supplying an existing OAuth
client, register the deployment’s connector callback URL with that client.
It must exactly match the redirect URI used by Introspection.
The dashboard runs discovery before presenting its client fields. The REST
discovery route is POST /v1/connectors/discover-oauth; its response includes
the endpoints, how the client will be obtained, and the exact redirect_uri to
register. It is separate from
MCP tool discovery, which requires an endpoint and an authorized connection.
Pipedream settings
Create a pipedream connector with auth_mode: client_credentials, a client ID
and secret, and the Pipedream Connect project ID in
metadata.provider_workspace_id. In the CLI, pass it as
--metadata provider_workspace_id=<project-id>. Creation validates access to
that Pipedream project.
The control plane sets metadata.provider_environment from the connector’s
environment and sets api_hosts to remote.mcp.pipedream.net; values you
send for either are overwritten.
A production connector uses Pipedream’s production environment; development
and staging connectors use its development environment. The connector’s API
scope is fixed. During authorization, app selects the downstream application,
such as notion, and runtime records the required runtime association.
allow_progressive_scopes defaults to false; enable it only for applications
that support granting a subset of their configured permissions.
Successful account authorization also creates an MCP endpoint binding for the
selected runtime in every environment. Its URL is
https://remote.mcp.pipedream.net/v3 and its server ID is the application slug,
such as notion. A Recipe uses the application’s tools by declaring that server
ID. Pipedream caps authorization links at four
hours. The dashboard can search the Pipedream application catalog. The REST
route is GET /v1/connectors/{connector_id}/apps with optional q and limit.
Connection fields
| Field | Meaning |
|---|---|
id | The connection ID returned by resource create, get, and list. Interactive CLI authorization reports it as connection_id. |
connector_id | The connector that owns the authorization. |
subject_type | app, user, workspace, federated, or person. Authorization accepts the supported subject kinds for that flow. |
member_id | The credential owner. An app connection has no member owner; user and workspace connections have one. |
created_by_member_id | The member who performed the grant, which can differ from the credential owner. |
status | pending_authorization, active, refresh_failed, or revoked. |
scopes_granted | The permissions the provider granted, which can be narrower than those requested. |
runtime_group_id | The runtime selected during authorization for a provider that requires one. |
provider_app | The application slug within a multi-application provider such as Pipedream. Empty for other providers. |
provider_account_id | The provider’s identifier for the connected account. |
token_expires_at | The stored token’s expiry, when supplied by the provider. |
Connection resource responses omit access and refresh tokens. Connector resource responses omit client and signing secrets. The separate token broker intentionally returns a provider token to an authorized caller.
Selecting a connection and testing access
POST /v1/oauth/connections/token accepts connector_id, optional
connection_id, and a subject that defaults to app. Without connection_id,
the broker resolves a connection from the authenticated subject. An exact ID
still has to belong to that connector and subject. It does not permit access
to another customer’s credential.
The CLI’s connections token --connection passes the exact ID. Its optional
request document can set subject to app, user, or person. For person
authorization, the document can also supply action and
requested_permissions.
connectors test and describe --connection use the default app subject.
They require exactly one project MCP endpoint whose server ID matches the
connector slug. They do not select endpoints by runtime or environment, and
they do not test Pipedream account authorization. Use the effective
binding listing and a representative task to verify a runtime with several
environment bindings or a provider workspace connection.
A successful discovery result proves that initialization and tool listing worked at the tested URL. It does not prove permission for every tool action.
Access and availability
| Operation | Required capability |
|---|---|
| List and read connectors and connections; broker a token; list Pipedream apps. | connectors:read |
| Create and update a connector; discover OAuth settings; register a connection; mint an authorization link. | connectors:write |
| Delete a connector; revoke a connection. | connectors:delete |
Creating a connector also requires member context. Deletion and revocation
require a member session because connectors:delete is not an API key or
application capability.
Error behavior
| Response or CLI failure | What to check |
|---|---|
404 with Connectors are not enabled. | The deployment has disabled connectors. |
422 during authorization. | A required runtime or Pipedream app is missing, or provider settings are incomplete. |
400 or 422 during discovery or creation. | Required client credentials are missing, public-client PKCE is unsupported, or Pipedream validation failed. |
404 with No connection for this subject. | The connection is missing or does not belong to the requested subject. An exact ID does not override ownership. |
409 from the token broker. | The connection is pending authorization, refresh failed, or its token expired. Reauthorize before retrying discovery. |
409 when asserting a new customer identity. | Creating the customer would exceed the organization’s member limit. |
202 with authorization_pending. | A person-authorized request needs approval. The response includes a mission ID and approval URL. |
400 stating an auth mode is not servable. | The public token broker does not serve the selected mode, including Pipedream client_credentials. |
| CLI reports no MCP endpoint or several matching endpoints. | Inspect the endpoint bindings for the connector slug and intended runtime. Do not remove valid environment overrides to satisfy the project-wide lookup. |
Related
- Connectors provides the setup workflow.
- CLI connector reference lists commands and project selection.
- Bindings explains endpoint scope and authentication.
- Operator in Slack explains incoming Operator conversations from an organization Slack installation.