Connectors

Use a connector when an agent needs to act through a provider account. The account can belong to your organization or to one of your customers. Introspection stores the provider credential and applies it to outgoing requests, so the credential stays outside the agent’s sandbox.

To give an agent access to an API or MCP service, configure the following:

Connectors belong to a project. Use separate connectors for provider apps with different staging and production credentials. The connector’s environment, provider, auth_mode, and slug are set at creation.

To let people start Operator work from your organization’s Slack workspace, follow Operator’s Slack setup. A channel binding selects the project for each Slack channel. For a Recipe agent, its channel declarations enable the tools it uses to read and reply. Customer-owned connector apps can also receive provider events, as described under Inbound events.

Set up an OAuth MCP server

The following example connects an OAuth-protected MCP server to an existing support-agent runtime in development. Its recipe must declare the MCP server ID support-tools. Before running the commands, obtain the server’s OAuth issuer URL and full MCP URL, and log in to the intended project with introspection login.

Create the connector

Replace the example issuer and host with the values for your server:

introspection connectors create \
  --name "Support tools" \
  --slug support-tools \
  --provider support-tools \
  --auth-mode oauth-stored \
  --environment development \
  --issuer https://mcp.example.com \
  --api-host mcp.example.com

--issuer lets Introspection discover the authorization and token endpoints. When the issuer supports dynamic client registration, Introspection can also register the OAuth client. Otherwise, include --client-id and any client secret the issuer requires. Register https://<control-plane-host>/v1/oauth/connections/callback as the OAuth client’s redirect URI, replacing the host with your deployment’s Control Plane host. The provider must have that exact URI. Public OAuth clients must support PKCE with S256. The reference describes the supported discovery and registration settings.

Creating a connector with the same slug again returns the existing connector. Use connectors update to change its mutable settings or rotate a stored client secret.

Authorize an account

Run interactive authorization when you are granting access yourself:

introspection connectors authorize support-tools

The CLI opens the provider in your browser and waits for completion. Keep the returned connection_id for the discovery check below. By default, the connection belongs to the project rather than an individual user.

To let a customer authorize their own account, generate a link with authorize-url instead:

introspection connectors authorize-url support-tools \
  --expires-in 1h

authorize-url returns the URL and its expiry immediately. Use it in scripts or when your application presents the link to a customer. Add --return-url to send the customer back to your application after authorization; the URL must satisfy the deployment’s redirect policy.

Each link can be used once. Its default lifetime is ten minutes, and --expires-in accepts 60 seconds to one day. Pipedream caps the returned link lifetime at four hours. Create a fresh link for each recipient and attempt.

Bind the endpoint

Create the MCP endpoint before testing discovery:

introspection bindings mcp connect \
  --mcp-server-id support-tools \
  --endpoint-url https://mcp.example.com/mcp \
  --connector support-tools \
  --runtime support-agent \
  --environment development
 
introspection bindings mcp list \
  --runtime support-agent \
  --environment development

--connector accepts a connector ID or slug and lets the endpoint use the authorized account. The server ID must match the Recipe declaration. Confirm that the listing marks the server as declared and shows the intended endpoint for development.

The same --connector option works on API endpoint create and update. See Bindings for its scope and authentication rules.

Check discovery

For the app connection created above, replace the placeholder with the exact connection_id returned by authorization:

introspection connectors test support-tools --connection <connection-id>
introspection connectors describe support-tools --connection <connection-id>

test initializes the MCP server and lists its tools using the selected connection. describe --connection returns the server ID, URL, and tools. A successful result confirms that the connection can initialize the server and list tools at that URL.

Run a representative task in the intended environment to confirm that the agent can perform the operations it needs. The connector reference explains how these commands choose an endpoint and connection when your project has several of them.

Connect a Pipedream application

Pipedream uses one connector definition with a separate authorization for each connected application account. Obtain a Pipedream Connect project ID and OAuth client credentials, then create the connector:

introspection connectors create \
  --name Pipedream \
  --slug pipedream \
  --provider pipedream \
  --auth-mode client-credentials \
  --environment development \
  --pipedream-project-id "$PIPEDREAM_PROJECT_ID" \
  --client-id "$PIPEDREAM_CLIENT_ID" \
  --client-secret "$PIPEDREAM_CLIENT_SECRET"

Introspection validates the credentials against the Pipedream project. A production connector uses Pipedream’s production environment; development and staging connectors use its development environment. The connector’s Pipedream API scope is fixed, so you do not supply a separate connector scope list.

Select the downstream application and runtime when authorizing:

introspection connectors authorize pipedream \
  --runtime support-agent \
  --app notion

Use authorize-url with the same options to hand the link to a customer. Add --allow-progressive-scopes only when the application supports granting a subset of its configured permissions. Successful authorization records the connected application account. Complete the MCP setup supported by your application before using its tools in a task.

Manage connections

List connections to inspect their IDs, subjects, status, and granted scopes:

introspection connectors connections list --connector support-tools
introspection connectors connections get <connection-id> --connector support-tools

When a customer grants access, pass --user-id or --anonymous-id to the authorization command to associate the grant with that customer in your application. See the CLI reference for these options.

To disconnect an account, revoke its connection:

introspection connectors connections revoke <connection-id> --connector support-tools

Revocation removes the credential and its approvals. Reconnecting requires a fresh authorization link. The connector and its other connections remain available.

How the runtime uses the connection

For an API or MCP endpoint, the binding chooses the URL and connector. When a task calls the endpoint, Introspection uses an authorized account for that task or the project’s shared connection. Introspection adds the credential to the outgoing request outside the sandbox.

The recipe’s MCP declarations select server IDs and tools. Keep endpoint URLs and credentials in bindings. For an ordinary bound server, the declaration matches metadata.mcp_server_id; the connector ID is a separate reference. The CLI’s connector discovery commands currently use the connector slug as the server ID. A provider-supplied MCP server uses its provider ID, such as linear. For Slack, use recipe channel tools, which call Slack’s Bot API.

The provider scopes and the Recipe’s tool settings both limit what the agent can do. Test a representative operation because listing the available tools does not confirm permission to use every one.

Inbound events

Customer-owned Slack connector apps can receive signed provider events. Register their delivery URL as https://{control-plane-host}/v1/webhooks/{provider}/{connector_id}. Because the URL includes the connector ID, create the connector first with the provider client ID, then add its webhook URL and signing secret with connectors update. The client ID is a create-time field. Supply Slack’s authorization and token endpoints and the scopes your tools require on create; the CLI does not apply the dashboard’s provider template. Register the deployment’s OAuth callback URL with the Slack app as well.

Authorization for Slack, Linear, and Pipedream requires a runtime. Read the connector’s requires_runtime field to decide whether to request one. For inbound connector events, the authorized connection determines the runtime and reply credential. Linear currently provides outgoing access; its inbound connector route is not exposed by the API.

Organization Slack installations for Operator use channel bindings to assign external conversations to a project. Use Recipe channels for a Recipe agent’s tool declarations and reply behavior.

Clients and related setup

Use the CLI to manage connectors and authorization. A backend that presents customer consent links can call the REST authorization route in the Control Plane API schema.

• Connectors reference lists provider behavior, fields, and errors.
• Bindings explains endpoint scope and authentication.
• MCP and federation explains task identity at partner endpoints.
• Operator in Slack connects organization Slack conversations to Operator.
• Operator investigates production behavior, tests Recipe changes, and prepares pull requests for the agents in your project.
• Automations explains how to schedule recurring Operator work.