Connectors

Use connectors when your customers own the accounts that an agent needs to use. You register a provider app, such as Slack, Linear, Gmail, or Stripe, once for your project. Your product then gives each customer a link to authorize their account. Introspection records each authorized account as a connection that the agent can use.

A connector defines the integration, and a connection records an authorization:

Every connection belongs to a connector. Each connection route, SDK method, and CLI command therefore names the connector first.

See the Connectors reference for supported provider features, authentication modes, connection fields, and errors.

Set up a connector

Set up a provider app and connector in the following order:

1. Create the connector. Provide name, provider, and auth_mode. If you omit slug, Introspection creates it from the name. Repeating the request with the same slug returns the existing connector instead of creating another one.
2. Register the provider app. In the provider’s settings, use the delivery URL for the connector, https://{control-plane-host}/v1/webhooks/{provider}/{connector_id}. The URL contains the connector ID, so you must create the connector first.
3. Update the connector. Add the client_id, client_secret, signing_secret, and webhook_url issued by the provider.

If the provider app already exists, include its credentials when you create the connector and skip the registration step.

The delivery URL is the address where the provider sends events to Introspection. It includes the connector ID so Introspection knows which connector should receive each event. Copy the URL from step 2 into the provider app’s webhook settings.

introspection connectors create --name "Slack support" \
  --provider slack --auth-mode oauth-stored \
  --scope chat:write --scope channels:read --api-host slack.com

const connector = await client.connectors.create({
  name: "Slack support",
  slug: "slack-support",
  provider: "slack",
  auth_mode: "oauth_stored",
  scopes: ["chat:write", "channels:read"],
  api_hosts: ["slack.com"],
});

Most integrations in which a customer authorizes their own account use oauth_stored. The customer gives consent once, and the resulting token belongs to their connection. See the full list of modes in the Connectors reference.

Give a customer the authorization link

The authorize method creates a consent URL for your customer. The customer opens the URL and approves your provider app in their account. The provider then sends a callback to Introspection, which creates the connection.

Choose one method to create the URL. Use the JS SDK in your application. Use the CLI when you want to create a URL by hand while setting up or testing the connector. Both examples create a URL, so you do not need to run both.

introspection connectors authorize slack-support \
  --runtime support-agent \
  --expires-in 1h

const install = await client.connectors.authorize(connector.id, {
  runtime: "support-agent",
  expires_in: 3600,
});
console.log(install.authorize_url);

The response includes expires_in, which contains the remaining lifetime in seconds. It also includes expires_at, which contains the expiration time.

The URL is valid for 600 seconds by default. You can increase the lifetime to 86400 seconds, or one day, when you send the URL to someone who may not open it within ten minutes.

The CLI and SDK do not open the URL in a browser. Your application normally sends the URL to a customer.

Record which customer authorized the connection

Introspection can record the credential owner and the person who authorized a connection separately:

• member_id identifies the owner of the credential. For a Slack workspace installation, it is the workspace’s customer member. It is null when the subject is an app owned by the organization.
• created_by_member_id identifies the member who authorized the connection.

Pass identity to authorize to identify the customer who is authorizing the connection. Introspection resolves identity.user_id to a customer member and stores the member as created_by_member_id. The connection is then associated with your customer instead of the agent member that made the API call. The identity value has the same structure as the identity used when opening a runner.

Connections

Use the following commands to list connections or disconnect a customer:

introspection connectors connections list --connector slack-support
introspection connectors connections revoke <CONNECTION_ID> --connector slack-support

for await (const connection of client.connectors.connections.list(connector.id)) {
  console.log(connection.id, connection.subject_type, connection.status);
}
 
await client.connectors.connections.revoke(connector.id, connectionId);

Revoking a connection deletes its provider token and disconnects the subject immediately. The subject must use a new authorization link to connect again. Revocation also removes approvals recorded for the connection, so an approval cannot remain valid after its credential is gone. The connector and its other connections are not affected.

See the Connectors reference for connection fields such as subject_type, status, and scopes_granted.

How an agent uses a connector

An agent uses a connector only through MCP tools. The sandbox does not contain a connector HTTP client.

The recipe’s MCP declarations control which server tools the model receives. The package policy limits all agents in the recipe, and each agent selects tools within that limit. The MCP server ID is the app slug rather than the connector ID or name. Using the app slug lets the same recipe work in projects that use different connector records.

The recipe does not name the connector itself. An authorized connection is what makes the server reachable. For a chat provider, the connection also records the runtime that answers its channels, and a task the provider starts carries that origin, so the runtime mounts the server for that task. For a provider whose MCP server is hosted elsewhere, the endpoint is mounted for the runtime as an ordinary MCP binding.

Provider scopes never appear in the recipe. Introspection records them when the customer authorizes the connection.

Where the MCP server runs

Each placement gives the recipe the same MCP interface. Placement does not change how Introspection handles credentials.

The credential never enters the sandbox

The sandbox receives a session locator and connector details that are not secret. It never receives an OAuth access token, refresh token, client secret, or provider API key. The egress proxy controls outgoing requests. It validates the session, finds the connection assigned to the task, and replaces the locator with the provider credential. It also limits requests to the hosts and paths allowed by the connector.

A session can use only the connection assigned to its task. Connector credentials never appear in the sandbox environment or conversation transcript. The package and agent MCP policies limit which tools the model can use.

Provider failures appear as MCP tool errors. Introspection does not automatically retry provider writes that could produce a different result when repeated.

Inbound events

A verified provider event can start or continue a task. The webhook first verifies the provider’s signature and finds the connection. It ignores a duplicate event and maps a new event to a customer or channel identity. It then sends the event to the runtime assigned to the connection. The connection supplies the credential for the reply, so the reply returns to the customer workspace that sent the event.

Person-authorized actions

A person_authorized connector requires a person to approve each action. A mission records the specific action that the agent proposes. The person can approve, limit, or deny the mission before Introspection creates a provider token. The token broker is the service that issues provider tokens. If the action does not have an approved mission, the token broker returns 202 and authorization_pending instead of a token. The response also includes a mission ID and an approval URL. After approval, Introspection retries the action within the limits recorded on the mission.

The Control Plane records the approval, and the egress layer checks it before sending a provider request. The agent continues to use the provider through MCP and never receives the credential.

Clients

You can manage connectors with the CLI or the JavaScript, Python, and Rust SDKs. Each command and method uses the project assigned to the credential that authenticated the request.

• CLI: Use introspection connectors and the nested connectors connections commands. You can identify a connector by ID or slug.
• JavaScript, Python, and Rust: Use connectors on the main client and connections under it.

Only the SDKs can request provider tokens. The CLI does not print temporary provider credentials to a terminal.

Related

• Connectors reference: Supported provider features, authentication modes, connection fields, and errors.
• MCP and federation: How a task identity reaches a partner endpoint.
• MCP tool declarations: How a recipe controls access to tools from a connector MCP server.
• Bindings: Endpoints, variables, and credentials owned by your project instead of a customer’s provider account.
• Tags: How to group and share a customer’s tasks and files.
• Security: How Introspection keeps provider credentials outside the sandbox.