Start a sign-in that connects an account or MCP server to one agent.

POST/o/{org}/agents/{agent}/connections
View .md

Starts the sign-in for one of the connections the agent's template names, for the user of your app the agent serves. That person needs no Rush account: send them to authorize_url, where they sign in to the app or the MCP server with Rush's OAuth client; the link works once and expires in 10 minutes. Then read the connection by its id until status is connected.

type is app for a built-in app (outlook, gmail, …) or mcp for an MCP server that signs in with OAuth; name is the name the template's connection has (GET /o/{org}/agents/{agent} lists them under connections). An MCP server is signed in to at the same address as the template's. A Gmail or Outlook connection the template names with an access level asks the user for that level alone. Connecting the same name again replaces the agent's earlier connection of it.

Authenticate with a signed-in session token (an API key cannot call this route).

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

agentstringrequired

The id or name of an agent made from a template (POST /o/{org}/agents {template, name}).

Request body

typestringrequired
One ofappmcp
namestringrequired

One of the connections the template names, e.g. outlook or notion.

Responses

202The sign-in, pending until the agent's user finishes it.
idstringrequired
Format uuid
typestringrequired
One ofappmcp
namestringoptional

The name a session's connections and the template use.

agentstringrequired

The agent the connection belongs to.

Format uuid
urlstringoptional

The MCP server's address.

Format uri
authobjectoptional
1 fields
modestringoptional
One ofoauthbearernone
statusstringrequired
One ofpendingconnectedfailed
authorize_urlstringoptional

Where the agent's user signs in. Single use; expires in 10 minutes.

Format uri
errorobjectoptional
2 fields
codestringoptional
One ofconnection_expiredcancelled_by_callerconnection_failed
messagestringoptional
toolsarray of objectoptional
4 item fields
namestringoptional
titlestringoptional
descriptionstringoptional
read_onlybooleanoptional
400The body is not {type, name} (INVALID_BODY, UNKNOWN_FIELD).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such agent made from a template of yours (NOT_FOUND).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
422The template does not name that connection, the MCP server takes a token rather than a sign-in, or the agent is not made from a template (INVALID_BODY); or the server cannot register Rush (registration_unsupported, registration_failed, …).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED).

The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED). The error names the limit. Wait Retry-After seconds.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional