Skip to Content
Platform
ShipConnect OAuth apps

Connect OAuth apps

A connector is an app your runtime signs in to with OAuth. Define it once in the manifest, then authorize it per runtime.

A connector holds an app’s OAuth client: Slack, Linear, Notion, or an MCP server of your own. A connection is one authorization against it, and the platform injects its token into outgoing requests, so the agent never sees it. A connector named like an MCP server the recipe declares backs that server.

You need: a deployed runtime (Deploy your agent) and, for an MCP server, its declaration in package.json (Connect an MCP server).

1. Define connectors

List them under runtime.connectors in the runtime manifest. For an MCP server, use its id from package.json as the slug:

.introspection/support-agent.yaml
runtime: connectors: [slack, linear, contacts]

Merge to the default branch. Each version keeps the list from its own commit, so a change applies from the next merge.

2. Connect them from the runtime page

The runtime page lists each connector the runtime still needs, per environment. Connect creates the connector from the server URL when the project has none, Authorize opens the provider’s sign-in, and the platform binds the endpoint and lists the server’s tools to confirm it works. The Bindings page offers the same flow.

3. Or connect them with the CLI

The example server below is MCP’s public reference server, which needs no OAuth app of your own: discovery finds its endpoints and registers a client automatically.

introspection connectors create --name "Contacts" --slug contacts --provider custom \ --auth-mode oauth-stored --issuer https://example-server.modelcontextprotocol.io/mcp introspection bindings mcp connect --mcp-server-id contacts \ --endpoint-url https://example-server.modelcontextprotocol.io/mcp \ --connector contacts -r support-agent -e staging introspection connectors authorize contacts -r support-agent

authorize opens your browser and waits for the connection. Use connectors authorize-url instead to get a link to send to whoever signs in. Pass --scope for each scope the server’s scopes_supported metadata lists, since the connector otherwise requests none; this server lists none.

Verify

introspection bindings mcp list --runtime support-agent -e staging introspection connectors connections list --connector contacts

The runtime and Bindings pages show each connected server’s tool check: a tick when every tool the recipe includes is listed, a cross with the reason otherwise.

Limits

Symptom or limitFix
Runtime page offers a plain URL binding instead of the connectorThe runtime’s version predates the connector in its manifest. Merge to build a new version.
Check says the connector can’t authenticate youNothing is authorized yet for this runtime: run connectors authorize.
Connector create returns 422 “client_id is required”The provider has no automatic client registration. Register an OAuth app there and pass --client-id and --client-secret-from-env.
Each user should act as themselvesUse per-user connections (Per-user tool access).

Or ask your agent: “Define a Linear connector for support-agent and connect it in staging.”

Last updated on