> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP connections

> Connect external MCP servers to your account and let genies call a chosen set of their tools during conversations

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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> Saved sign-ins and tokens are never returned by any action.

***

## The connection object

**id** `string`

Connection UUID.

**user\_id** `string`

UUID of the person who added the connection.

**name** `string`

The name the owner gave the connection, for example `"printIQ"`.

**url** `string`

The server's https MCP endpoint.

**auth\_type** `string`

`"oauth"`, `"bearer"`, `"header"` or `"none"`.

**scopes** `string[]`

OAuth scopes asked for. Empty for other connection types.

**status** `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`.

**own** `boolean`

`true` when the caller added the connection. `false` for a teammate's connection, which can be given to genies but not changed.

**owner\_name** `string | null`

Name (or email) of the person who added the connection.

**genies** `object[]`

Genies using the connection: `{ id, name }`. Returned by `list`; empty elsewhere.

**connected\_at** `string | null`

ISO 8601 timestamp of the first successful connection.

**invalid\_at** `string | null`

ISO 8601 timestamp when the server stopped accepting the sign-in or token.

**created\_at** `string`

ISO 8601 creation timestamp.

**updated\_at** `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.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"list"`

**data** `object`

**properties**

**connections** `object[]`

[Connection objects](#the-connection-object).

```typescript TypeScript theme={null}
const { connections } = await ApiService.invoke("mcp-connections", "list");
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resource": "mcp-connections", "action": "list" }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "connections": [
      {
        "id": "conn-uuid",
        "user_id": "user-uuid",
        "name": "printIQ",
        "url": "https://mcp.example.com/mcp",
        "auth_type": "oauth",
        "scopes": ["printiq.read"],
        "status": "connected",
        "own": true,
        "owner_name": "Alex Smith",
        "genies": [{ "id": "agent-uuid", "name": "Support Genie" }],
        "connected_at": "2026-11-01T09:00:00.000Z",
        "invalid_at": null,
        "created_at": "2026-11-01T08:58:00.000Z",
        "updated_at": "2026-11-01T09:00:00.000Z"
      }
    ]
  }
}
```

***

## 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`.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"create"`

**data** `object` *required*

**properties**

**name** `string` *required*

What you call the server, for example `"printIQ"`. Up to 80 characters.

**url** `string` *required*

The server's public https MCP endpoint.

**authType** `string` (default: auto)

`"auto"`, `"oauth"`, `"bearer"` (token sent as `Authorization: Bearer`), `"header"` (token sent in `headerName`) or `"none"`.

**token** `string`

Required for `bearer` and `header`.

**headerName** `string`

Required for `header`, for example `"X-API-Key"`. Letters, digits and hyphens, up to 64 characters.

**scopes** `string[] | string`

OAuth only. Scopes to ask for instead of the ones the server advertises. A string is split on spaces.

**clientId** `string`

OAuth only. A client the server issued to you. Without it, Help Genie registers itself with the server.

**clientSecret** `string`

OAuth only. That client's secret.

> [!NOTE]
>
> 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`](#finish-a-sign-in). The sign-in link works for 15 minutes. A server that needs a sign-in, connected from outside the app, returns `VALIDATION_ERROR`.

**data** `object`

**properties**

**connection** `object`

The new [connection](#the-connection-object). `status` is `"pending"` until an OAuth sign-in is finished.

**url** `string`

OAuth only. The sign-in link to open in the browser.

**toolCount** `number`

Token, header and open connections only. Number of tools the server offers.

```typescript TypeScript theme={null}
const { connection, toolCount } = await ApiService.invoke("mcp-connections", "create", {
  data: {
    name: "Orders",
    url: "https://mcp.example.com/mcp",
    authType: "header",
    headerName: "X-API-Key",
    token: "your-server-api-key",
  },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "create",
    "data": {
      "name": "Orders",
      "url": "https://mcp.example.com/mcp",
      "authType": "header",
      "headerName": "X-API-Key",
      "token": "your-server-api-key"
    }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "connection": {
      "id": "conn-uuid",
      "name": "Orders",
      "url": "https://mcp.example.com/mcp",
      "auth_type": "header",
      "scopes": [],
      "status": "connected",
      "own": true,
      "genies": []
    },
    "toolCount": 7
  }
}
```

***

## Get a sign-in link

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`](#update-a-connection) instead.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"authorize"`

**data** `object` *required*

**properties**

**connectionId** `string` *required*

Connection UUID.

**data** `object`

**properties**

**url** `string`

The sign-in link. Works for 15 minutes.

```typescript TypeScript theme={null}
const { url } = await ApiService.invoke("mcp-connections", "authorize", {
  data: { connectionId: "conn-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "authorize",
    "data": { "connectionId": "conn-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": { "url": "https://auth.example.com/authorize?client_id=...&state=..." }
}
```

***

## 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`.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"callback"`

**data** `object` *required*

**properties**

**code** `string` *required*

From the callback page link.

**state** `string` *required*

From the callback page link.

**data** `object`

**properties**

**connection** `object`

The [connection](#the-connection-object), now `"connected"`.

```typescript TypeScript theme={null}
const { connection } = await ApiService.invoke("mcp-connections", "callback", {
  data: { code: "server-code", state: "signed-state" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "callback",
    "data": { "code": "server-code", "state": "signed-state" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "connection": { "id": "conn-uuid", "name": "printIQ", "status": "connected", "own": true }
  }
}
```

***

## 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"`.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"tools"`

**data** `object` *required*

**properties**

**connectionId** `string` *required*

Connection UUID.

**data** `object`

**properties**

**serverName** `string`

The name the server reports for itself.

**tools** `object[]`

**item properties**

**name** `string`

Tool name, as passed to `attach`.

**title** `string | null`

Display title.

**description** `string | null`

What the tool does.

**readOnly** `boolean`

From the server's own read-only hint.

**destructive** `boolean`

`true` unless the server marks the tool read-only or not destructive.

```typescript TypeScript theme={null}
const { tools } = await ApiService.invoke("mcp-connections", "tools", {
  data: { connectionId: "conn-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "tools",
    "data": { "connectionId": "conn-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "serverName": "printIQ",
    "tools": [
      {
        "name": "find_customers",
        "title": "Find customers",
        "description": "Search customers by name or email",
        "readOnly": true,
        "destructive": false
      }
    ]
  }
}
```

***

## 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`.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"update"`

**data** `object` *required*

**properties**

**connectionId** `string` *required*

Connection UUID.

**name** `string`

New name, up to 80 characters.

**token** `string`

New token. `bearer` and `header` connections only.

**data** `object`

**properties**

**connection** `object`

The updated [connection](#the-connection-object).

```typescript TypeScript theme={null}
const { connection } = await ApiService.invoke("mcp-connections", "update", {
  data: { connectionId: "conn-uuid", token: "new-server-api-key" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "update",
    "data": { "connectionId": "conn-uuid", "token": "new-server-api-key" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "connection": { "id": "conn-uuid", "name": "Orders", "status": "connected", "own": true }
  }
}
```

***

## 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).

> [!WARNING]
>
> This action is destructive and cannot be undone.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"delete"`

**data** `object` *required*

**properties**

**connectionId** `string` *required*

Connection UUID.

```typescript TypeScript theme={null}
await ApiService.invoke("mcp-connections", "delete", {
  data: { connectionId: "conn-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "delete",
    "data": { "connectionId": "conn-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": { "ok": true }
}
```

***

## The link object

A link gives one genie a set of one connection's tools.

**id** `string`

Link UUID, passed to `genie-update` and `detach` as `linkId`.

**agent\_id** `string`

Genie UUID.

**connection\_id** `string`

Connection UUID.

**tools** `string[]`

The tools the genie may call. Tools the server adds later stay off until you add them.

**settings** `object`

**properties**

**pre\_tool\_speech** `string`

`"auto"`, `"force"` or `"off"` — whether the genie says something like "let me check" before calling a tool.

**response\_timeout\_secs** `number`

How long the genie waits for the server, 5–60 seconds. Default `30`.

**connection** `object | null`

The [connection](#the-connection-object).

**created\_at** `string`

ISO 8601 creation timestamp.

**updated\_at** `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.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"genie-list"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**data** `object`

**properties**

**links** `object[]`

[Link objects](#the-link-object).

```typescript TypeScript theme={null}
const { links } = await ApiService.invoke("mcp-connections", "genie-list", {
  data: { agentId: "agent-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "genie-list",
    "data": { "agentId": "agent-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "links": [
      {
        "id": "link-uuid",
        "agent_id": "agent-uuid",
        "connection_id": "conn-uuid",
        "tools": ["find_customers"],
        "settings": { "pre_tool_speech": "auto", "response_timeout_secs": 30 },
        "connection": { "id": "conn-uuid", "name": "printIQ", "status": "connected", "own": true },
        "created_at": "2026-11-01T09:05:00.000Z",
        "updated_at": "2026-11-01T09:05:00.000Z"
      }
    ]
  }
}
```

***

## 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.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"attach"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**connectionId** `string` *required*

Connection UUID.

**tools** `string[]` *required*

1–100 tool names returned by `tools`, each once.

**settings** `object`

**properties**

**pre\_tool\_speech** `string` (default: auto)

`"auto"`, `"force"` or `"off"`.

**response\_timeout\_secs** `number` (default: 30)

Whole number from 5 to 60.

**data** `object`

**properties**

**link** `object`

The new [link](#the-link-object).

```typescript TypeScript theme={null}
const { link } = await ApiService.invoke("mcp-connections", "attach", {
  data: {
    agentId: "agent-uuid",
    connectionId: "conn-uuid",
    tools: ["find_customers"],
    settings: { pre_tool_speech: "auto", response_timeout_secs: 20 },
  },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "attach",
    "data": {
      "agentId": "agent-uuid",
      "connectionId": "conn-uuid",
      "tools": ["find_customers"],
      "settings": { "pre_tool_speech": "auto", "response_timeout_secs": 20 }
    }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "link": {
      "id": "link-uuid",
      "agent_id": "agent-uuid",
      "connection_id": "conn-uuid",
      "tools": ["find_customers"],
      "settings": { "pre_tool_speech": "auto", "response_timeout_secs": 20 },
      "connection": { "id": "conn-uuid", "name": "printIQ", "status": "connected" }
    }
  }
}
```

***

## 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.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"genie-update"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**linkId** `string` *required*

A link `id` from `genie-list`.

**tools** `string[]`

Replaces the tool list. 1–100 tool names, each once.

**settings** `object`

As in `attach`. Merged with the current settings.

**data** `object`

**properties**

**link** `object`

The updated [link](#the-link-object).

```typescript TypeScript theme={null}
const { link } = await ApiService.invoke("mcp-connections", "genie-update", {
  data: { agentId: "agent-uuid", linkId: "link-uuid", tools: ["find_customers", "get_order"] },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "genie-update",
    "data": { "agentId": "agent-uuid", "linkId": "link-uuid", "tools": ["find_customers", "get_order"] }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "link": {
      "id": "link-uuid",
      "tools": ["find_customers", "get_order"],
      "settings": { "pre_tool_speech": "auto", "response_timeout_secs": 20 }
    }
  }
}
```

***

## Take tools away from a genie

Takes a connection's tools away from the genie. The connection stays on the account.

**resource** `string` *required*

Must be `"mcp-connections"`

**action** `string` *required*

Must be `"detach"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**linkId** `string` *required*

A link `id` from `genie-list`.

```typescript TypeScript theme={null}
await ApiService.invoke("mcp-connections", "detach", {
  data: { agentId: "agent-uuid", linkId: "link-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "mcp-connections",
    "action": "detach",
    "data": { "agentId": "agent-uuid", "linkId": "link-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": { "ok": true }
}
```

***

## Error codes

| Code | Meaning |
| - | - |
| `VALIDATION_ERROR` | A required field is missing or invalid, the server couldn't be reached or didn't list its tools, a tool name isn't offered by the server, the connection isn't `"connected"` (`tools`, `attach`), the sign-in link expired (`callback`), the connection has no OAuth sign-in (`authorize`) or no token (`update`), or an OAuth sign-in was started outside the Help Genie app |
| `UNAUTHORIZED` | You do not have access to this genie |
| `FORBIDDEN` | You are not the person who added the connection (`authorize`, `callback`, `update`, `delete`), or you have no access to the connection |
| `NOT_FOUND` | The connection doesn't exist, or the link isn't on this genie (`genie-update`, `detach`) |
| `CONFLICT` | The genie already uses this connection (`attach`) |
| `INTERNAL_ERROR` | Unexpected server error |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.