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

# Overview

> Enable AI agents to search, register, and connect domains through Entri's MCP server.

## Overview

Model Context Protocol (MCP) is an open standard that gives AI agents a consistent, secure way to discover and use external tools and services. The **Entri MCP server** exposes Entri Connect and Sell products as MCP tools, allowing AI assistants to handle domain operations on behalf of your users entirely within the conversation.

**MCP Server URL:** `https://mcp.entri.com/mcp`

Depending on which Entri product and registrar are configured for your account, the MCP tools behave differently:

* **Entri Connect** — Returns a sharing link the user follows to connect an existing domain to your platform.
* **Entri Sell (IONOS / Squarespace)** — Returns a sharing link the user follows to purchase a domain through the registrar's checkout.
* **Entri Sell Enterprise (direct registration)** — Registers domains directly on the user's behalf, with optional purchase authorization and Lightning Mode for zero-friction flows.

***

## Authentication

Entri MCP uses **OAuth 2.0 machine-to-machine (M2M) authentication**, following the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) and the **client credentials grant** defined in [RFC 6749 §4.4](https://www.rfc-editor.org/rfc/rfc6749#section-4.4).

Your **Client ID** and **Client Secret** (available in the Dashboard) are used to obtain a short-lived access token from the OAuth Authentication URL. That token is then passed as a Bearer token on each MCP request.

**Token request:**

```http theme={null}
POST https://mcp.entri.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&userId=END_USER_ID
&geo=us
```

| Parameter       | Required | Description                                            |
| --------------- | -------- | ------------------------------------------------------ |
| `grant_type`    | Yes      | Must be `client_credentials`                           |
| `client_id`     | Yes      | Your Client ID from the Dashboard                      |
| `client_secret` | Yes      | Your Client Secret from the Dashboard                  |
| `userId`        | No       | ID of the end user on whose behalf the request is made |
| `geo`           | No       | Geographic region for the request (e.g. `us`, `fr`)    |

**Token response:**

```json theme={null}
{
  "access_token": "eyJ...",
  "token_type": "Bearer"
}
```

Use the returned `access_token` as a Bearer token on all MCP requests:

```
Authorization: Bearer {access_token}
```

<Note>
  MCP hosts using `mcp-remote` (VS Code, Cursor, etc.) can pass credentials directly as `Authorization: Bearer YOUR_CLIENT_ID:YOUR_CLIENT_SECRET` in the configuration JSON — no token exchange needed. For programmatic or server-side integrations, use the OAuth flow above.
</Note>

***

## Dashboard — MCP Settings

All MCP configuration is managed under **Dashboard → Application Settings → MCP Settings**.

### MCP Connection Credentials

These credentials are used to authenticate your MCP server with Entri. Find them under the **MCP Connection** section of MCP Settings.

| Field                        | Description                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| **Client ID**                | Your application identifier. Read-only, copyable.                                  |
| **Client Secret**            | Your secret key. Masked by default. Rotatable from Application Settings.           |
| **OAuth Authentication URL** | Token endpoint for obtaining short-lived access tokens (client credentials grant). |
| **MCP Server URL**           | The remote MCP server endpoint to configure in your MCP host.                      |

***

### Entri Connect Settings

Configure how the MCP retrieves DNS records and provider options for Connect domain flows. The `connect-domain` tool always returns a **sharing link** — this setting determines what configuration is pre-loaded when the user opens that link.

#### Configuration Source

<Tabs>
  <Tab title="Static Configuration">
    Use Static Configuration when every user needs the same DNS records. Provide a single Entri configuration that will be applied to all Connect flows.

    ```json theme={null}
    {
      "whiteLabel":{
        ...
      },
      "dnsRecords": [
        { "type": "A", "host": "@", "value": "93.184.216.34", "ttl": 300 }
      ],
      //... every other optional key
    }
    ```
  </Tab>

  <Tab title="Dynamic Endpoint">
    Use Dynamic Configuration when each user needs a unique set of DNS records. Provide an endpoint URL that Entri will call per-request to retrieve the full configuration.

    Entri authenticates requests to your endpoint using **Basic Authentication**. Provide the username and password in the fields below the URL.

    **Endpoint requirements:**

    * Must accept `GET` requests.
    * Must support Basic Authentication.
    * Entri will include `userId` as a query string parameter (e.g. `?userId=abc123`) so you can return a user-specific configuration.
    * Must return an Entri configuration object. Minimal example:

    ```json theme={null}
    {
      "applicationId": "your-application-id",
      "dnsRecords": [
        {
          "host": "@",
          "type": "TXT",
          "ttl": 300,
          "value": "this-is-a-sample-value"
        }
      ]
    }
    ```

    For the full configuration reference, see the [API Reference](/api-reference).
  </Tab>
</Tabs>

***

### Entri Sell Settings

Configure how the MCP retrieves DNS records and whitelabel options for Sell domain purchase flows. This applies when your account uses a **sharing registrar** (IONOS or Squarespace) — the purchase flow is presented to the user as a link.

#### Configuration Source

<Tabs>
  <Tab title="Static Configuration">
    Use Static Configuration when every user needs the same DNS records and branding. Provide a single Entri configuration applied to all Sell flows.

    ```json theme={null}
    {
      "whiteLabel":{
        ...
      },
      "dnsRecords": [
        { "type": "A", "host": "@", "value": "93.184.216.34", "ttl": 300 }
      ],
      //... every other optional key
    }
    ```
  </Tab>

  <Tab title="Dynamic Endpoint">
    Use Dynamic Configuration when each order requires a unique set of DNS records or custom branding. Provide an endpoint URL that Entri will call per-request.

    Entri authenticates requests to your endpoint using **Basic Authentication**. Provide the username and password in the fields below the URL.

    **Endpoint requirements:**

    * Must accept `GET` requests.
    * Must support Basic Authentication.
    * Entri will include `userId` as a query string parameter (e.g. `?userId=abc123`) so you can return a user-specific configuration.
    * Must return an Entri configuration object. Minimal example:

    ```json theme={null}
    {
      "applicationId": "your-application-id",
      "dnsRecords": [
        {
          "host": "@",
          "type": "TXT",
          "ttl": 300,
          "value": "this-is-a-sample-value"
        }
      ]
    }
    ```

    For the full configuration reference, see the [API Reference](/api-reference).
  </Tab>
</Tabs>

***

### Entri Sell Enterprise Settings

These settings are available on Entri Sell Enterprise.

#### Purchase Authorization

Enable this toggle to require authorization before each domain purchase is processed. When enabled, Entri calls your endpoint and expects an approval decision before registering the domain. When disabled, purchases proceed automatically.

Entri authenticates requests to your authorization endpoint using **Basic Authentication**. Provide the endpoint URL, username, and password in the Purchase Authorization section.

See [Purchase Authorization](#purchase-authorization) for the full endpoint contract.

***

## How Each Product Works via MCP

The behavior of `create-domain-order` and `connect-domain` depends on which Entri product and registrar are configured for your account. The registrar is resolved automatically from your application settings in this order:

1. If `preferred_registrar` is `"ionos"` or `"squarespace"` → sharing registrar flow
2. Else if direct registration is enabled → Sell Enterprise flow
3. Otherwise → no registrar configured; domain tools will return an error

### Entri Connect

The `connect-domain` tool generates a **sharing link** that the user must open to complete DNS configuration. Entri's guided flow walks the user through logging in to their DNS provider and applying the required records.

* The AI agent must present the link to the user and ask them to open it.
* DNS propagation status is tracked with `check-connection-status` using the returned `jobId`.
* The DNS records and provider options loaded in the flow are sourced from your **Entri Connect Settings** (Static or Dynamic).

### Entri Sell — IONOS / Squarespace

When your account uses IONOS or Squarespace as the registrar, `create-domain-order` returns a **sharing link** instead of registering the domain directly. The user must follow the link to complete the purchase through the registrar's checkout.

* The AI agent must present the link and ask the user to complete the purchase.
* Order progress is tracked with `check-order-status` using the returned `jobId`.
* The DNS records and whitelabel configuration for the purchase flow come from your **Entri Sell Settings** (Static or Dynamic).

### Entri Sell Enterprise

With Entri Sell Enterprise, `create-domain-order` **registers the domain directly** — no redirect or external checkout required.

* If **Purchase Authorization** is enabled, Entri calls your authorization endpoint before registering. The domain is only registered if your endpoint returns `200`. See [Purchase Authorization](#purchase-authorization).
* If **Lightning Mode** is enabled, contact details are sourced automatically from your Sell Settings. The AI agent does not need to collect them from the user. See [Lightning Mode](#lightning-mode).
* Order progress is tracked with `check-order-status` using the returned `orderId`.

**Summary:**

| Product / Registrar        | `create-domain-order` outcome         | User action required?                       |
| -------------------------- | ------------------------------------- | ------------------------------------------- |
| Sell — IONOS / Squarespace | Returns a sharing link + `jobId`      | Yes — user completes checkout via the link  |
| Sell Enterprise            | Registers domain directly + `orderId` | No (unless authorization is rejected)       |
| Connect (`connect-domain`) | Returns a DNS config link + `jobId`   | Yes — user completes DNS setup via the link |

***

## Purchase Authorization

<Info>
  Purchase Authorization is available on Entri Sell Enterprise.
</Info>

Purchase Authorization lets you enforce business rules before a domain is registered — entirely on the backend, invisible to the end user. When the toggle is enabled, Entri calls your endpoint after the AI agent requests a registration, and proceeds only if you approve.

**Common use cases:**

* **Balance validation** — Check if the user has sufficient credits or funds.
* **Spending limits** — Enforce per-user domain quotas or monthly purchase caps.
* **Fraud prevention** — Block suspicious registration patterns before they complete.
* **Manual approval** — Gate expensive or sensitive domains behind admin review.

### How It Works

1. AI agent calls `create-domain-order(domain: "example.com")`.
2. Entri calls `POST {your_authorization_url}` using the Basic Auth credentials configured in the Dashboard.
3. Your endpoint validates the request and responds with an HTTP status code.
4. Entri acts on the response:
   * `200` → Domain registration proceeds.
   * `401` → Registration is rejected; the AI agent receives an error.
   * Any other code → Treated as an error; registration is blocked and an email alert is sent to your account.

### Endpoint Response Contract

<CodeGroup>
  ```json Approved (HTTP 200) theme={null}
  {
    "dnsRecords": [
      { "type": "A", "host": "@", "value": "93.184.216.34", "ttl": 300 },
      { "type": "CNAME", "host": "www", "value": "example.com", "ttl": 300 }
    ]
  }
  ```

  ```http Rejected (HTTP 401) theme={null}
  (no response body)
  ```
</CodeGroup>

<Info>
  The `dnsRecords` array in the `200` response is applied to the domain upon successful registration. This lets you return user-specific DNS records dynamically at authorization time, rather than relying on a static configuration.
</Info>

<Warning>
  If your authorization endpoint is unreachable, times out, or returns any code other than `200` or `401`, the registration is blocked and an email alert is sent to your account. Make sure your endpoint is highly available when this toggle is enabled.
</Warning>

***

## Lightning Mode

<Info>
  Lightning Mode is available on Entri Sell Enterprise.
</Info>

Lightning Mode lets you pre-configure a single set of contact details that Entri applies automatically to every domain registration. When enabled, the AI agent no longer needs to collect contact information from the user — domains can be registered with a single conversational prompt.

**The goal is zero-friction domain registration.** Instead of the AI agent asking for name, address, phone, and email before registering, the user just says "register example.com" and it's done.

**When Lightning Mode is ON:**

* The `create-domain-order` tool uses the contact details saved in **Dashboard → Application Settings → Sell Settings** for all contact types (Owner, Technical, and Registrant).
* ICANN email notifications — including verification emails — are **not sent**.
* Any `contactDetails` passed by the AI agent are ignored.

**When Lightning Mode is OFF:**

* The AI agent will ask the end user for their contact details directly in the chat before completing the registration.
* ICANN emails are sent normally.

### Configure Lightning Mode

1. Navigate to **Dashboard → Application Settings → Sell Settings**.
2. Enable the **Lightning Mode** toggle.
3. Fill in the default contact information:
   * First Name, Last Name
   * Email address
   * Phone number with country code (e.g., `+15551234567`)
   * Address, City, State, ZIP code, Country
4. Click **Save Contact**.

<Note>
  The contact information saved here is applied uniformly to all contact types — Owner, Technical, and Registrant. You can update these details at any time, and all subsequent registrations will use the updated values.
</Note>

***

## MCP Tools

The Entri MCP server exposes 6 tools across the Connect and Sell products. For the full reference — including parameters, response shapes, and status values — see the [MCP Tool Reference](/entri-mcp-tools).