---
name: "connect_add"
area: "connect"
title: "Connect a system"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/connect_add"
mcp_server: "https://api.conecto.chat/mcp/connect"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/connect/connect_add"
---

# Connect a system (`connect_add`)

Connects one of the company's systems: its address, its credential (kept encrypted) and the calls it may make.

Connect one of the company's own systems (an ERP, a ticketing tool, any REST API): its https base address, its credential and the calls the agent may make. The credential is kept encrypted and never shown again. A system behind the company's firewall goes through one of its bridges instead: give `bridge` and `system` (connect_list shows the bridges and the systems each serves) in place of base_url and a credential, which the bridge adds inside the network. On accounts with an owner, writes (POST, PUT, PATCH, DELETE) and changing the allowed calls wait for the owner's approval by default, which shows the exact request. Free.

Price: Free. A call that fails costs nothing.

## Use it when

The agent needs to read or change something in a system that has a REST API.

## Say this to your agent

> Connect our Zendesk so you can read tickets and close the ones we moved. Here is the API token.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `name` | string | yes | Lowercase letters, digits and dashes, like "netsuite" or "zendesk". 2 to 40 characters. |  |  |
| `base_url` | string | no | Up to 500 characters. |  |  |
| `auth` | string | no | bearer (Authorization: Bearer <secret>), header (the secret in `header`), basic (secret is "user:password") or none. | `"bearer"`, `"header"`, `"basic"`, `"none"` | `"bearer"` |
| `header` | string | no | For auth header, like X-API-Key. Up to 60 characters. |  |  |
| `secret` | string | no | Up to 4,000 characters. Stored encrypted and shown only as [redacted]. |  |  |
| `allow` | array of strings | yes | The calls it may make: a method and a path pattern each, like "GET /v1/customers*" or "POST /v1/tickets". * matches anything. 1 to 50 items. |  |  |
| `description` | string | no | Up to 300 characters. |  |  |
| `bridge` | string | no | For a system behind the firewall: the bridge it goes through. Up to 40 characters. |  |  |
| `system` | string | no | With bridge: the system's name in the bridge's config, like "sap". Up to 40 characters. |  |  |

## Example

Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff.

MCP: call `connect_add` on the MCP server `https://api.conecto.chat/mcp/connect` with these arguments:

```json
{
  "name": "zendesk",
  "base_url": "https://hansenvoss.zendesk.com/api/v2",
  "auth": "bearer",
  "secret": "zd-example-token",
  "allow": [
    "GET /tickets*",
    "PUT /tickets/*"
  ],
  "description": "The old help desk, until the move is done"
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/connect_add \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "zendesk", "base_url": "https://hansenvoss.zendesk.com/api/v2", "auth": "bearer", "secret": "zd-example-token", "allow": ["GET /tickets*", "PUT /tickets/*"], "description": "The old help desk, until the move is done"}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "connect_add",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "connection": {
      "name": "zendesk",
      "base_url": "https://hansenvoss.zendesk.com/api/v2",
      "auth": "bearer",
      "header": null,
      "allow": [
        "GET /tickets*",
        "PUT /tickets/*"
      ],
      "description": "The old help desk, until the move is done",
      "created_at": "2026-10-14T08:00:00+00:00",
      "last_used_at": null
    },
    "writes_need_approval": true
  }
}
```

`result`: connection: its name, base address, kind of auth, allowed calls and description; writes_need_approval, true when POST, PUT, PATCH and DELETE wait for the owner.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | The name, address, auth or an allowed call is not valid, or the secret is missing. | Fix what the message names. |
| `conflict` | 409 | A connection with that name exists. | Pick another name, or remove the old one. |
| `limit_reached` | 409 | The account has 50 connections. | Remove one first. |
| `not_found` | 404 | The bridge, or the system on it, does not exist. | connect_list shows the account's bridges and the systems each serves. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [connect_list](https://conecto.chat/tools/connect/connect_list.md): The connected systems with their address, auth and allowed calls, and this month's call count. Free up to 1,000,000 reads a month.
- [connect_preview](https://conecto.chat/tools/connect/connect_preview.md): Shows exactly what a call would send (method, full address, headers with the credential hidden, body) without sending it. Free up to 1,000,000 reads a month.
- [connect_call](https://conecto.chat/tools/connect/connect_call.md): Sends one request to a connected system, inside its allowed calls, and returns its answer. $0.0003 for each started 10 seconds the system takes to answer ($0.0003 when it answers within 10 seconds), up to $0.0012.
- [connect_set_rules](https://conecto.chat/tools/connect/connect_set_rules.md): Replaces a connection's allowed calls; waits for the owner's approval by default. $0.001 a call.
- [connect_remove](https://conecto.chat/tools/connect/connect_remove.md): Forgets a connected system and its credential; the system itself doesn't change. Free.