Connect an MCP with a setup link

This flow lets you build an MCP onboarding experience on top of the Platform API: create a connection in draft, hand a secure link to a client or third party so they can authenticate with their own credentials (without a Nekt account), receive a webhook when they finish, then activate the connection. It mirrors the in-app MCPs flow end to end over the API, and it is the same shape as Configure a source with a setup link — a different resource, and a different link prefix (/lcl/ instead of /scl/).

The case this exists for: one connection per end client, each with their own credentials. Create as many connections of the same connector as you have clients — each has its own slug, its own credentials, and its own permissions.

Overview

Prerequisites

An API key for authentication.
MCPs are available on all paid plans.

Step 1: Pick a connector

List the connectors available to your workspace. Expand the current version to get the JSON Schema that a connection for it is configured against — that is what tells you which fields the third party will be asked for.

curl --request GET \
  --url "https://api.nekt.ai/api/v1/live-connectors/?expand[]=current_version&include[]=current_version.config_template" \
  --header "x-api-key: YOUR_API_KEY"

Step 2: Create a draft connection with a callback webhook

The connection is created as a draft, pinned to the connector’s current version. Optionally attach a callback_webhook: Nekt POSTs to it once the third party submits the setup form. Use the optional custom header to authenticate the call on your side.

curl --request POST \
  --url https://api.nekt.ai/api/v1/live-connections/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "connector": "CONNECTOR_ID_OR_SLUG",
    "slug": "hubspot-acme",
    "description": "ACME'\''s HubSpot",
    "callback_webhook": {
      "url": "https://your-app.example.com/hooks/nekt",
      "header_name": "X-Webhook-Secret",
      "header_value": "your-shared-secret"
    }
  }'

Field	Type	Required	Description
`connector`	string	Yes	The connector this connection is for.
`slug`	string	No	Stable identifier, generated when omitted. It is also the namespace the connection’s tools are exposed under, so keep it recognisable.
`description`	string	No	Read by the agent to choose between connections of the same type (“HubSpot for marketing” vs “HubSpot for sales”).
`available_tools`	array	No	Which of the connector’s tools this connection exposes. Defaults to all of them.
`callback_webhook`	object	No	See below.

`callback_webhook` object

Field	Type	Required	Description
`url`	string	Yes	HTTPS URL Nekt POSTs to on setup completion. Must be a public `https://` endpoint.
`header_name`	string	No	Optional custom header name to send with the callback.
`header_value`	string	No	Value for the custom header. Required if `header_name` is set. Stored encrypted and never returned.

callback_webhook is write-only. Responses never echo it back; they expose a read-only boolean has_callback_webhook so you can confirm one is configured. To remove a configured webhook, send "callback_webhook": null on an update.

For security, the URL must use https and resolve to a public host. URLs pointing at localhost, loopback, private (RFC 1918), or link-local addresses are rejected.

Step 3: Create a setup token

Generate a time-limited token scoped to this connection, then build the link as https://app.nekt.ai/lcl/{token} and share it with the third party.

curl --request POST \
  --url https://api.nekt.ai/api/v1/live-connections/{slug}/setup-tokens/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "expires_in_seconds": 86400 }'

{
  "id": "0d2c1b47-2902-4c47-8b30-0e7c3fd72609",
  "token": "Qm9vR2k...redactedOnList",
  "expires_at": "2026-06-18T12:00:00Z",
  "connector_config_fields": null,
  "created_at": "2026-06-17T12:00:00Z"
}

Field	Type	Required	Description
`expires_in_seconds`	integer	No	Token lifetime. Defaults to 24 hours (`86400`).
`connector_config_fields`	array, object or boolean	No	Restricts which configuration fields the link exposes. Omit for the whole config template. See Restricting the link.

The full token is returned only on creation. When listing tokens it is redacted. To revoke a link, delete the token: DELETE /api/v1/live-connections/{slug}/setup-tokens/{id}/.

Step 4: The third party authenticates

The recipient opens https://app.nekt.ai/lcl/{token} and enters the credentials (or authenticates via OAuth for connectors that support it). No Nekt account is required, and the link is scoped strictly to this connection. When they submit, Nekt POSTs to your callback_webhook (if configured):

POST https://your-app.example.com/hooks/nekt
Content-Type: application/json
X-Webhook-Secret: your-shared-secret

{
  "event": "live_connection.setup_filled",
  "live_connection": {
    "id": "d2c1b472-902c-477a-b300-e7c3fd72609b",
    "slug": "hubspot-acme",
    "connector_slug": "hubspot",
    "description": "ACME's HubSpot",
    "draft": true,
    "active": false,
    "config_completed": true,
    "missing_required_fields": []
  }
}

Field	Type	Description
`config_completed`	boolean	`true` when all required configuration fields are filled.
`missing_required_fields`	array	Dot-paths of required fields still missing. Empty when `config_completed` is `true`.

Read config_completed, not draft. The connection stays draft until you activate it in the next step, so draft never answers “did my client finish?”. A partially filled form produces config_completed: false with the remaining fields named — send another link to collect them.

Step 5: Activate the connection

Activating clears draft and puts the connection in service: its tools become available to your agents through the Gateway.

curl --request PATCH \
  --url https://api.nekt.ai/api/v1/live-connections/{slug}/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "active": true }'

Setup links stop working once the connection is active. Any unused link for it is invalidated at that moment, and a link can be used again only if the connection later goes into an error state and needs re-authentication.

Restricting what the link exposes

By default a setup link exposes the connector’s whole configuration template. connector_config_fields narrows it: the setup page renders only the named fields, and anything else the recipient sends back is ignored rather than written — a hidden field keeps its stored value.

curl --request POST \
  --url https://api.nekt.ai/api/v1/live-connections/{slug}/setup-tokens/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "connector_config_fields": ["api_key"] }'

Value	Meaning
omitted / `null`	No restriction — the whole template.
`["api_key", "domain"]`	Those fields, nothing else.
`{"auth": {"token": true}}`	Nested: only `auth.token`, and only `token` within `auth`.
`true` / `false`	Everything / nothing, at any level.

A typical use: your systems already know the account id and region, so you send them as config when you create the connection and restrict the link to the one secret only your client has.

Naming a field the connector’s template does not declare is rejected with 400 when the link is created, listing every unknown path at once — rather than producing a link whose page is silently empty.

Choosing which tools the connection exposes

A connection is created exposing every tool of the connector. Send available_tools at creation, or replace the set later — the payload is the full desired set, so anything missing from the list stops being exposed.

curl --request PATCH \
  --url https://api.nekt.ai/api/v1/live-connections/{slug}/tools/ \
  --header "x-api-key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "tools": ["search_objects", "get_object"] }'

GET the same endpoint to list the connector’s tools with an is_write flag on each, so you can enable write-capable tools deliberately.

The exact endpoints and request/response shapes are available in the OpenAPI schema at api.nekt.ai/api/schema/.

Platform API

Activities

Connectors

Sources

MCP connections

Connector validations

Transformations

Destinations

Runs

Catalog

Semantic Layer

MCP Tokens

Users

Permissions

Visualizations

Tags

API Tokens

Token Access Logs

Connect an MCP with a setup link

Overview

Prerequisites

Step 1: Pick a connector

Step 2: Create a draft connection with a callback webhook

`callback_webhook` object

Step 3: Create a setup token

Step 4: The third party authenticates

Step 5: Activate the connection

Restricting what the link exposes

Choosing which tools the connection exposes

​Overview

​Prerequisites

​Step 1: Pick a connector

​Step 2: Create a draft connection with a callback webhook

​callback_webhook object

​Step 3: Create a setup token

​Step 4: The third party authenticates

​Step 5: Activate the connection

​Restricting what the link exposes

​Choosing which tools the connection exposes

Overview

Prerequisites

Step 1: Pick a connector

Step 2: Create a draft connection with a callback webhook

`callback_webhook` object

Step 3: Create a setup token

Step 4: The third party authenticates

Step 5: Activate the connection

Restricting what the link exposes

Choosing which tools the connection exposes