Skip to main content
MCP connections let a genie use tools from an external server that speaks the Model Context Protocol (Streamable HTTP), such as a CRM or order system. You connect the server to your account once, then give each genie only the tools it should be able to call. A genie can call nothing else on that server. A connection belongs to the person who added it. Teammates see it in list and can give its tools to their genies, but only the person who added it (or an admin) can rename it, sign in again or delete it.
A genie can tell a caller anything the connected account can see, and it sends what the caller says to the connected server. For genies that strangers talk to, pick read-only tools only.
Saved sign-ins and tokens are never returned by any action.

The connection object

string
Connection UUID.
string
UUID of the person who added the connection.
string
The name the owner gave the connection, for example "printIQ".
string
The server’s https MCP endpoint.
string
"oauth", "bearer", "header" or "none".
string[]
OAuth scopes asked for. Empty for other connection types.
string
  • "connected" — ready to use.
  • "pending" — the sign-in was never finished. Call authorize for a new sign-in link.
  • "reconnect" — the server stopped accepting the sign-in or token. Call authorize (OAuth) or replace the token with update.
boolean
true when the caller added the connection. false for a teammate’s connection, which can be given to genies but not changed.
string | null
Name (or email) of the person who added the connection.
object[]
Genies using the connection: { id, name }. Returned by list; empty elsewhere.
string | null
ISO 8601 timestamp of the first successful connection.
string | null
ISO 8601 timestamp when the server stopped accepting the sign-in or token.
string
ISO 8601 creation timestamp.
string
ISO 8601 last update timestamp.

List connections

Returns the MCP servers the caller and their teammates connected, newest first, each with its status and the genies using it.
string
required
Must be "mcp-connections"
string
required
Must be "list"
object

Create a connection

Connects an MCP server to the caller’s account. With authType: "auto" (the default), the server says whether it needs a sign-in: one that does gets an OAuth connection and the response includes the sign-in link to open in the browser; one that doesn’t is connected straight away. Token, header and open connections are checked by listing the server’s tools before they are saved. If that fails, nothing is saved and the request returns VALIDATION_ERROR.
string
required
Must be "mcp-connections"
string
required
Must be "create"
object
required
An OAuth sign-in can only be started from the Help Genie app: the server sends the user back to /genie-hub/connections/mcp/callback, which calls callback. The sign-in link works for 15 minutes. A server that needs a sign-in, connected from outside the app, returns VALIDATION_ERROR.
object

Returns a new sign-in link for an OAuth connection: to finish connecting it, or to connect it again after it stopped working. Genies using the connection keep working with the new sign-in. Only the person who added the connection (or an admin). Must be called from the Help Genie app. Connections without OAuth return VALIDATION_ERROR; replace their token with update instead.
string
required
Must be "mcp-connections"
string
required
Must be "authorize"
object
required
object

Finish a sign-in

Finishes an OAuth sign-in with the code and state the server sent back to the callback page. Must be called by the person who started the sign-in, within 15 minutes. An expired or mismatched state returns VALIDATION_ERROR.
string
required
Must be "mcp-connections"
string
required
Must be "callback"
object
required
object

List a server’s tools

Returns the tools the server offers right now, to pick which ones a genie may use. Works for your own and your teammates’ connections. The connection must be "connected".
string
required
Must be "mcp-connections"
string
required
Must be "tools"
object
required
object

Update a connection

Renames a connection, or replaces the token of a bearer or header connection. A new token clears the "reconnect" status. Only the person who added the connection (or an admin). Pass at least one of name or token.
string
required
Must be "mcp-connections"
string
required
Must be "update"
object
required
object

Delete a connection

Deletes a connection and its saved sign-in. Every genie using it loses its tools. Only the person who added the connection (or an admin).
This action is destructive and cannot be undone.
string
required
Must be "mcp-connections"
string
required
Must be "delete"
object
required

A link gives one genie a set of one connection’s tools.
string
Link UUID, passed to genie-update and detach as linkId.
string
Genie UUID.
string
Connection UUID.
string[]
The tools the genie may call. Tools the server adds later stay off until you add them.
object
object | null
string
ISO 8601 creation timestamp.
string
ISO 8601 last update timestamp.

List a genie’s connections

Returns the MCP connections a genie uses, oldest first, each with the tools it may call. Requires access to the genie.
string
required
Must be "mcp-connections"
string
required
Must be "genie-list"
object
required
object

Give a genie tools

Gives a genie some of a connection’s tools. The genie can call only the tools listed, and each must be a tool the server offers now. The connection must be "connected" and can be your own or a teammate’s. A genie can have each connection once: if it already uses this one, the request returns CONFLICT — change its tools with genie-update instead.
string
required
Must be "mcp-connections"
string
required
Must be "attach"
object
required
object

Change a genie’s tools

Changes which of the connection’s tools the genie may use, or its settings. Newly added tools must be tools the server offers now.
string
required
Must be "mcp-connections"
string
required
Must be "genie-update"
object
required
object

Take tools away from a genie

Takes a connection’s tools away from the genie. The connection stays on the account.
string
required
Must be "mcp-connections"
string
required
Must be "detach"
object
required

Error codes