> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/mcp-tools/connectors.md).

# Connector tools

A connector is a saved, reusable definition of a connection to an external system — a database, a warehouse, object storage, a REST API, or a file source. These MCP tools manage the connector lifecycle: create and save a config, run a real connectivity test, browse its schema, update or delete it, and list what you have. Two preview variants test or browse an inline definition without persisting it. Every tool maps one-to-one to a `/v1` endpoint.

{% hint style="info" %}
For the everyday path — connect a source and get a queryable `dataset_id` in one step — use `connect_data` on the [Data and ingest tools](/mcp-tools/data.md) page. Reach for these connector tools when you want to explicitly manage saved, reusable connectors. For the full list of `connector_type` values and their config fields, see the [Connectors reference](/connectors/reference.md).
{% endhint %}

## The connector lifecycle

A new connector starts `untested`; a successful test moves it to `live`, a failed one to `error`. Browsing requires a `live` connector, and editing `config` resets it to `untested`.

| Tool                       | What it does                                                                              | Key inputs                                                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `list_connectors`          | List saved connectors; filter by status.                                                  | `status` (`untested` / `live` / `error` / `all`), `page`, `limit`.                                                             |
| `create_connector`         | Create and save one connector config for later onboarding, health checks, and browsing.   | `name` (required), `connector_type` (required); `config`, `description`, `visibility` (`private` / `organization` / `public`). |
| `get_connector`            | Fetch one saved connector by id.                                                          | `connector_id` (required).                                                                                                     |
| `update_connector`         | Update a saved connector's name, description, visibility, or config.                      | `connector_id` (required) + at least one of `name` / `description` / `visibility` / `config`.                                  |
| `test_connector`           | Run a real connectivity test for a saved connector and persist its `live`/`error` status. | `connector_id` (required).                                                                                                     |
| `browse_connector`         | Browse a saved `live` connector to discover files, tables, endpoints, or items.           | `connector_id` (required).                                                                                                     |
| `preview_test_connector`   | Test an inline connector definition without saving it.                                    | `connector_type` (required), `config`.                                                                                         |
| `preview_browse_connector` | Browse an inline connector definition without saving it.                                  | `connector_type` (required), `config`.                                                                                         |
| `delete_connector`         | Delete one saved connector by id.                                                         | `connector_id` (required).                                                                                                     |

## Method and endpoint

Because each tool is a one-to-one wrapper, you can reproduce any call against the raw endpoint.

| Tool                       | Method   | Endpoint                               |
| -------------------------- | -------- | -------------------------------------- |
| `list_connectors`          | `GET`    | `/v1/connectors`                       |
| `create_connector`         | `POST`   | `/v1/connectors`                       |
| `get_connector`            | `GET`    | `/v1/connectors/{connector_id}`        |
| `update_connector`         | `PATCH`  | `/v1/connectors/{connector_id}`        |
| `test_connector`           | `POST`   | `/v1/connectors/{connector_id}/test`   |
| `browse_connector`         | `GET`    | `/v1/connectors/{connector_id}/browse` |
| `preview_test_connector`   | `POST`   | `/v1/connectors/test`                  |
| `preview_browse_connector` | `POST`   | `/v1/connectors/browse`                |
| `delete_connector`         | `DELETE` | `/v1/connectors/{connector_id}`        |

## Worked examples

### Preview a config, then save it

Validate a config without persisting anything with `preview_test_connector`, then commit it with `create_connector`. This is the test-before-save pattern; inline previews are rate limited, so save and reuse a connector for production workflows.

```json
{
  "connector_type": "postgres",
  "config": {
    "host": "db.internal",
    "port": 5432,
    "database": "analytics",
    "user": "reader",
    "password": "$ALGENTA_DB_PASSWORD"
  }
}
```

```json
{
  "name": "analytics-pg",
  "connector_type": "postgres",
  "config": {
    "host": "db.internal",
    "port": 5432,
    "database": "analytics",
    "user": "reader",
    "password": "$ALGENTA_DB_PASSWORD"
  },
  "visibility": "organization"
}
```

The equivalent HTTP calls:

```bash
curl -s "$ALGENTA_BASE_URL/v1/connectors/test" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connector_type": "postgres", "config": { "host": "db.internal", "port": 5432, "database": "analytics", "user": "reader", "password": "'"$ALGENTA_DB_PASSWORD"'" } }'

curl -s "$ALGENTA_BASE_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "analytics-pg", "connector_type": "postgres", "config": { "host": "db.internal", "port": 5432, "database": "analytics", "user": "reader", "password": "'"$ALGENTA_DB_PASSWORD"'" }, "visibility": "organization" }'
```

### Test a saved connector, then browse it

A saved connector must pass `test_connector` (moving it to `live`) before `browse_connector` can enumerate its tables, files, or endpoints.

```json
{ "connector_id": "$CONNECTOR_ID" }
```

```bash
curl -s "$ALGENTA_BASE_URL/v1/connectors/$CONNECTOR_ID/test" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" -X POST

curl -s "$ALGENTA_BASE_URL/v1/connectors/$CONNECTOR_ID/browse" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"
```

{% hint style="warning" %}
`browse_connector` requires a `live` connector. If you browse an `untested` or `error` connector, the endpoint responds with `409 not_connected` — run `test_connector` first and confirm it passes.
{% endhint %}

### List only live connectors

Filter the list to connectors that last tested successfully.

```json
{ "status": "live", "limit": 25 }
```

```bash
curl -s "$ALGENTA_BASE_URL/v1/connectors?page=1&limit=25" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" | jq '.connectors[] | select(.status == "live") | .id'
```

## Related pages

{% content-ref url="/pages/lCqcj2JtRPaotaF5GJvm" %}
[Connectors reference](/connectors/reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/acj6XXSxQwONXUAEEH4m" %}
[Data & ingest tools](/mcp-tools/data.md)
{% endcontent-ref %}

{% content-ref url="/pages/oWVTrgfD6zfzaggU9IRO" %}
[Connect a data source](/guides/connect-data.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.algenta.ai/mcp-tools/connectors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.