Connect OAuth apps
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:
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-agentauthorize 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 contactsThe 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 limit | Fix |
|---|---|
| Runtime page offers a plain URL binding instead of the connector | The runtime’s version predates the connector in its manifest. Merge to build a new version. |
| Check says the connector can’t authenticate you | Nothing 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 themselves | Use per-user connections (Per-user tool access). |
Or ask your agent: “Define a Linear connector for support-agent and connect it in staging.”