> For the complete documentation index, see [llms.txt](https://docs.datasentinel.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasentinel.io/manual/guides/readme/connect-an-ai-assistant.md).

# Connect an AI Assistant to Datasentinel

From a fresh install or an upgrade to your first conversation with an AI assistant: MCP server, metrics, users, and first analyses.

<div data-with-frame="true"><figure><img src="https://114419588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmjcIrQjSJ5zQDGoUyWRn%2Fuploads%2Fgit-blob-64dd002e1ebf26211e99123e1ecb57146670d5c7%2Fai-connector.jpg?alt=media" alt="Connect an AI Assistant to Datasentinel"><figcaption></figcaption></figure></div>

[**AI Connector**](https://docs.datasentinel.io/ai-connector) opens Datasentinel metrics to AI assistants. You ask a question in plain language, and the assistant analyzes your PostgreSQL workload, explains what it finds, and turns the evidence into recommendations.

This guide is the path from a Datasentinel platform to that first conversation. It starts on the platform host, with a fresh install or an upgrade, and ends in the assistant, with the checks and the first questions a new user should run.

{% hint style="info" %}
No platform yet? You can try the whole assistant side against the public [**sandbox platform**](https://docs.datasentinel.io/ai-connector/getting-started/test-with-the-sandbox-platform) and skip the platform steps.
{% endhint %}

## How the pieces fit together

AI Connector is made of two parts, and this guide sets up both:

<table><thead><tr><th width="200">Part</th><th>Where it runs</th><th>What it does</th></tr></thead><tbody><tr><td><strong>MCP server</strong></td><td>On each Datasentinel platform server, behind nginx on the <code>/mcp</code> path</td><td>Exposes the platform metrics to assistants over the <a href="https://modelcontextprotocol.io/"><strong>Model Context Protocol</strong></a>. Protected by OAuth 2.1: users sign in with their platform login.</td></tr><tr><td><strong>Skill</strong></td><td>In the assistant, as a folder of instructions</td><td>Tells the assistant which tools to call, in which order, and how to turn the results into analyses, recommendations and a communication style adapted to the reader.</td></tr></tbody></table>

Any assistant that supports MCP and Skills works: Claude (desktop app, Claude Code), OpenAI Codex and ChatGPT, GitHub Copilot, Microsoft Copilot, Cursor, Visual Studio Code, Mistral Vibe, Google Antigravity, and more. See [**Connect a compatible assistant**](https://docs.datasentinel.io/ai-connector/getting-started/connect-a-compatible-assistant) for the general pattern.

## Before you start

<table><thead><tr><th width="240">Requirement</th><th>Detail</th></tr></thead><tbody><tr><td><strong>Datasentinel 2026.10 or later</strong></td><td>The MCP server ships with this release. See <a href="https://docs.datasentinel.io/manual/implementation/upgrade/platform.md"><strong>Upgrade the platform</strong></a> for the current version and the upgrade procedure.</td></tr><tr><td><strong>A licence with the AI Connector add-on</strong></td><td>AI Connector is enabled for the whole installation by a licence token that includes the option. Without it, every sign-in from an assistant is refused. Contact <a href="mailto:contact@datasentinel.io"><strong>Datasentinel</strong></a> to upgrade your licence.</td></tr><tr><td><strong>A host name with a trusted certificate</strong></td><td>Assistants verify the platform certificate, and cloud-hosted assistants (Claude, ChatGPT, Microsoft Copilot) need the platform reachable from the internet. A CA-signed certificate on nginx is highly recommended. See <a href="https://docs.datasentinel.io/ai-connector/troubleshooting/ssl-certificates"><strong>Self-signed and untrusted TLS certificates</strong></a>.</td></tr><tr><td><strong>A platform user per person</strong></td><td>Each user signs in to the assistant with their own Datasentinel login. The assistant then sees exactly what that user sees in the web interface.</td></tr><tr><td><strong>An AI assistant</strong></td><td>Installed on your workstation, or a cloud assistant such as Claude or ChatGPT, with the LLM of your choice.</td></tr></tbody></table>

***

## Step 1: Install or upgrade the platform

{% tabs %}
{% tab title="Fresh install" %}
Install the platform as described in [**Installation › Platform**](https://docs.datasentinel.io/manual/getting-started/installation/platform.md), then enable your licence key under [**License**](https://docs.datasentinel.io/manual/implementation/platform-usage/configuration/license.md).

On a fresh install, the MCP server is provisioned automatically: the `datasentinel_mcp` service, its sudoers rules and the nginx routes are all in place. Nothing is created by hand. If you are also onboarding your first instances, follow [**Install On-Premises and Configure Agentless Connections**](https://docs.datasentinel.io/manual/guides/readme/install-on-premises-and-agentless.md).
{% endtab %}

{% tab title="Upgrade" %}
Upgrade the platform to 2026.10 or later as described in [**Upgrade the platform**](https://docs.datasentinel.io/manual/implementation/upgrade/platform.md), and update the licence token with the AI Connector option under [**License**](https://docs.datasentinel.io/manual/implementation/platform-usage/configuration/license.md).

A platform upgraded from a release that predates the MCP server does not yet have the systemd unit, the sudoers rules and the nginx locations. Create them by following the [**Manual setup on upgrade**](https://docs.datasentinel.io/ai-connector/getting-started/mcp-server-setup#manual-setup-on-upgrade) steps: grant the service rights, install the `datasentinel_mcp` unit, add the `/mcp` and OAuth locations to the nginx site file, then reload nginx and start the service.

{% hint style="warning" %}
Remove any old `location ~ /.well-known` block from the HTTPS server of the nginx site file. It captures the OAuth discovery requests before the MCP server sees them, and assistants then fail to sign in.
{% endhint %}
{% endtab %}
{% endtabs %}

Whichever path you took, finish with the health check on the platform host:

```bash
/datasentinel/soft/datasentinel_backend/scripts/mcp_check.sh
```

The script connects to the internal listener and to the public URL through nginx, describes the certificate, probes every OAuth route, and ends with one verdict. `OK` means the MCP server is up and reachable the way an assistant reaches it. `WARNING` usually points at the certificate, and `FAILED` names the route or service to fix. The output is explained line by line in [**Verify the install**](https://docs.datasentinel.io/ai-connector/getting-started/mcp-server-setup#verify-the-install).

{% hint style="info" %}
If the public name of the platform is not the host name (a load balancer, a NAT, a DNS alias), set `DS_MCP_PUBLIC_URL` on the service with a systemd drop-in, as shown in [**Change a setting**](https://docs.datasentinel.io/ai-connector/getting-started/mcp-server-setup#change-a-setting). Every URL the server publishes derives from it.
{% endhint %}

***

## Step 2: Prepare the metrics

The assistant reasons over the metrics Datasentinel collects, so the depth of the collection sets the precision of its recommendations. Two optional setup points raise it significantly:

{% stepper %}
{% step %}

### Upgrade the local agents

If you collect metrics with local agents, upgrade them to [**Agent v4.0.0**](https://docs.datasentinel.io/manual/implementation/agent-usage/release-notes.md) or later. This release collects table and index sizes, the full list of PostgreSQL parameters, and serves the on-demand endpoints the assistant uses for real-time analyses: the current execution plan of a query, the progress of maintenance operations, and the live metrics of a table. See [**Upgrade the agent**](https://docs.datasentinel.io/manual/implementation/upgrade/agent.md).
{% endstep %}

{% step %}

### Install the internal function

The optional [**`datasentinel_analytics` function**](https://app.gitbook.com/s/lcWi6G1jtNuyGT9C0pkc/getting-started/postgresql-clusters/internal-function) gives Datasentinel read-only access to planner statistics and execution plans, without any SELECT privilege on application tables. With it, the assistant can estimate table and index bloat, read column and extended statistics, and explain the plan the planner would choose right now.

Install it in each application database with the `deploy_datasentinel_function.sh` script shipped with the agent. It never returns application data, and every other metric keeps working without it.
{% endstep %}
{% endstepper %}

***

## Step 3: Prepare the users

An assistant acts with the rights of the user who signed in, so the Datasentinel account shapes what the assistant can do. Review three settings under [**Users and Roles**](https://docs.datasentinel.io/manual/implementation/platform-usage/configuration/users-and-roles.md) before inviting users:

<table><thead><tr><th width="200">Setting</th><th>Effect in the assistant</th></tr></thead><tbody><tr><td><strong>Profile</strong></td><td>Selects the communication style. A <strong>Data admin</strong> gets the <strong>TECHNICAL</strong> style: PostgreSQL vocabulary and full measurements. A <strong>Developer</strong> gets the <strong>PLAIN</strong> style: plain language, the impact on the application, and an escalation for anything a DBA owns. When the profile cannot be determined, the assistant uses PLAIN.</td></tr><tr><td><strong>Live360 access</strong></td><td>Required for real-time analyses: current sessions, live blocking, running execution plans, maintenance progress. Without it, the assistant answers from the collected history only.</td></tr><tr><td><strong>Role</strong></td><td>Tag-based <a href="https://docs.datasentinel.io/manual/features/other-features/role-based-access.md"><strong>role-based access</strong></a> limits the instances the assistant can reach, exactly as it limits the dashboards.</td></tr></tbody></table>

Every user signs in from the assistant with their platform login and password, on the Datasentinel login page. Nothing is typed in the conversation, and no PostgreSQL credential is ever known to the assistant. See [**How authentication works**](https://docs.datasentinel.io/ai-connector/getting-started/how-authentication-works) for the full flow, including sign-in from a server without a browser.

{% hint style="info" %}
Administrators can list the sessions assistants hold and end them at any time with the `mcp_oauth_sessions.sh` script. See [**Manage assistant sessions**](https://docs.datasentinel.io/ai-connector/getting-started/manage-assistant-sessions). Every sign-in and tool call is also recorded under the user's email in [**mcp.log**](https://docs.datasentinel.io/ai-connector/troubleshooting/read-the-mcp-log).
{% endhint %}

For users and roles in general, see [**Manage Users and Role-Based Access**](https://docs.datasentinel.io/manual/guides/readme/manage-users-and-role-based-access.md).

***

## Step 4: Configure the assistant

The steps are the same for every assistant: register the MCP server, sign in once, install the Skill, check. The commands below show Claude Code and the Claude desktop app; the other assistants have their own page.

{% hint style="warning" %}
**Name every Datasentinel MCP server with the `datasentinel-` prefix**, for example `datasentinel-production`. The Skill discovers platforms by this prefix, so a server named otherwise is never picked up. Use a distinct suffix per platform when you operate several.
{% endhint %}

{% stepper %}
{% step %}

### Register the MCP server

{% tabs %}
{% tab title="Claude Code" %}

```bash
claude mcp add --scope user --transport http datasentinel-production https://<public-host>/mcp
```

Nothing else goes in the configuration: no token, no header.
{% endtab %}

{% tab title="Claude desktop app" %}
Open **Settings**, then **Connectors**, choose **Add custom connector**, name it `datasentinel-production` and paste the URL `https://<public-host>/mcp`. The platform must be reachable from the internet with a publicly trusted certificate. See [**Configure the Claude desktop app for Windows**](https://docs.datasentinel.io/ai-connector/getting-started/configure-claude-desktop-windows).
{% endtab %}

{% tab title="Other assistants" %}
Each assistant has its own configuration page in the AI Connector section: [**GitHub Copilot CLI**](https://docs.datasentinel.io/ai-connector/getting-started/configure-copilot-cli), [**OpenAI Codex CLI**](https://docs.datasentinel.io/ai-connector/getting-started/configure-codex-cli), [**Mistral Vibe CLI**](https://docs.datasentinel.io/ai-connector/getting-started/configure-mistral-vibe-cli), [**Google Antigravity CLI**](https://docs.datasentinel.io/ai-connector/getting-started/configure-antigravity-cli), [**ChatGPT desktop app**](https://docs.datasentinel.io/ai-connector/getting-started/configure-chatgpt-desktop-app), [**Microsoft Copilot app**](https://docs.datasentinel.io/ai-connector/getting-started/configure-microsoft-copilot-app), [**Microsoft Copilot Studio**](https://docs.datasentinel.io/ai-connector/getting-started/configure-copilot-studio), [**Google Gemini desktop app**](https://docs.datasentinel.io/ai-connector/getting-started/configure-gemini-desktop-app), [**Visual Studio Code**](https://docs.datasentinel.io/ai-connector/getting-started/configure-vscode) and [**Cursor**](https://docs.datasentinel.io/ai-connector/getting-started/configure-cursor). For any other MCP-capable assistant, follow [**Connect a compatible assistant**](https://docs.datasentinel.io/ai-connector/getting-started/connect-a-compatible-assistant).
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Sign in once

The first time the assistant uses the server, it asks to authenticate: **Authenticate** in the `/mcp` panel of Claude Code, **Connect** on the connector in the Claude apps. The Datasentinel login page opens in your browser. Sign in with your platform login and password.

The assistant keeps the session and renews it by itself. You sign in again only after ten days without using the server, or when an administrator ends the session.

On a server without a browser, such as an SSH session, run the sign-in in the mode that prints the link and paste the redirect address back:

```bash
claude mcp login datasentinel-production --no-browser
```

{% endstep %}

{% step %}

### Install the Skill

Download [**`datasentinel-skill.zip`**](https://app.datasentinel.io/ds-api/download/datasentinel-skill.zip) and unzip it into the Skills folder of your assistant. For Claude Code:

```bash
mkdir -p ~/.claude/skills/
unzip datasentinel-skill.zip -d ~/.claude/skills/
```

You end up with `~/.claude/skills/datasentinel/SKILL.md` next to the Skill's supporting files. The Skill is the same for every platform and every assistant: one copy serves all the `datasentinel-*` servers you register.

{% hint style="warning" %}
Connecting the MCP server is not enough. Without the Skill, the assistant sees the tools but does not know how to use them: no `datasentinel` commands, no guided analyses, no adapted communication style.
{% endhint %}
{% endstep %}

{% step %}

### Check the wiring

In Claude Code, `claude mcp list` shows the server as connected with a tool count, and `/skills` lists `datasentinel`. Then run the Skill's own checks, in this order:

<table><thead><tr><th width="260">Command</th><th>What it confirms</th></tr></thead><tbody><tr><td><code>/datasentinel help</code></td><td>The Skill is loaded. Needs no sign-in.</td></tr><tr><td><code>/datasentinel platforms</code></td><td>Your <code>datasentinel-*</code> server is discovered.</td></tr><tr><td><code>/datasentinel status</code></td><td>The platform answers through the MCP server, with every service running.</td></tr><tr><td><code>/datasentinel whoami</code></td><td>Who the session runs as: platform, identity, privilege, real-time access, style and language.</td></tr></tbody></table>

In an assistant without slash commands, write the same commands in the prompt: `datasentinel status`. See the [**Skill commands reference**](https://docs.datasentinel.io/ai-connector/skill-commands) and [**Check your session with whoami**](https://docs.datasentinel.io/ai-connector/whoami-command).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
If `/datasentinel status` reports a healthy platform, the MCP server and the Skill are wired together correctly.
{% endhint %}

***

## Step 5: Your first session

A session starts with a short banner that names the platform, the communication style (TECHNICAL or PLAIN) and the language in use. The language is the one of your first message, so write in the language you want the answers in.

Then ask real questions. A good first run moves from the inventory to one instance, then to one problem:

```
What do we monitor in production?
```

```
Which production instance was the busiest yesterday afternoon, and why?
```

```
Analyze the workload of prod-db-01 between 14:00 and 15:00 yesterday.
```

```
What is slowing orders-db down right now?
```

The assistant confirms the instance and the time window when the request leaves them open, lists its findings ordered by impact, and ends every analysis with a short menu of next steps: a deeper dive, a report, or a comparison. Each analysis area also has a named command, such as `datasentinel ash` or `datasentinel locks`, when you already know what you want.

<table><thead><tr><th width="260">To learn</th><th>Read</th></tr></thead><tbody><tr><td>What the assistant can analyze</td><td><a href="https://docs.datasentinel.io/ai-connector/what-you-can-analyze"><strong>What you can analyze</strong></a></td></tr><tr><td>Find your way in the inventory</td><td><a href="https://docs.datasentinel.io/ai-connector/examples/browse-your-fleet"><strong>Browse and navigate your fleet</strong></a></td></tr><tr><td>Explain a past window</td><td><a href="https://docs.datasentinel.io/ai-connector/examples/analyze-a-workload"><strong>Analyze a workload over a time window</strong></a></td></tr><tr><td>Act on the heaviest queries</td><td><a href="https://docs.datasentinel.io/ai-connector/examples/optimize-top-queries"><strong>Optimize your top queries</strong></a></td></tr><tr><td>Troubleshoot live</td><td><a href="https://docs.datasentinel.io/ai-connector/examples/diagnose-live-spike"><strong>Diagnose a live performance spike</strong></a></td></tr></tbody></table>

{% hint style="info" %}
The style can be switched at any time: say "switch to plain language" or "switch to technical" (or simply "I'm a DBA") and the assistant changes style immediately.
{% endhint %}

***

## Step 6: Go further

Once the first analyses run, three additions make the assistant part of the daily routine:

* **Reports.** Ask for a platform PDF report of one instance, or an HTML or Markdown report of the analysis on screen, to attach to a ticket or a post-mortem. See [**Generate and share reports**](https://docs.datasentinel.io/ai-connector/generate-reports).
* **The documentation at hand.** Register the documentation MCP server, named `docs-datasentinel`, next to your platform: the assistant then answers product questions from the manual while it works on your databases. See [**Explore the documentation from your assistant**](https://docs.datasentinel.io/ai-connector/explore-the-documentation).
* **Automation.** Schedule a daily health check or a weekly digest, or let Claude render your metrics as a live dashboard. See [**Run recurring analyses**](https://docs.datasentinel.io/ai-connector/examples/recurring-analyses) and [**Build a dynamic dashboard**](https://docs.datasentinel.io/ai-connector/examples/dynamic-dashboard-artifact).

Operating several platforms? Register each one with its own `datasentinel-` name and the assistant switches between them, or gives a global view. See [**Work with several platforms**](https://docs.datasentinel.io/ai-connector/examples/work-with-several-platforms).

***

## Troubleshooting

<table><thead><tr><th width="320">Symptom</th><th>Where to look</th></tr></thead><tbody><tr><td>The sign-in is refused with a message about the licence</td><td>The licence has no AI Connector add-on. See <a href="https://docs.datasentinel.io/ai-connector/troubleshooting/sign-in-problems"><strong>Sign-in problems</strong></a>.</td></tr><tr><td>The assistant cannot connect, or rejects the certificate</td><td><a href="https://docs.datasentinel.io/ai-connector/troubleshooting/ssl-certificates"><strong>Self-signed and untrusted TLS certificates</strong></a> and <a href="https://docs.datasentinel.io/ai-connector/troubleshooting/tls-hostname-mismatch"><strong>TLS hostname mismatch</strong></a>.</td></tr><tr><td>The login page opens on a host name the browser cannot reach</td><td><a href="https://docs.datasentinel.io/ai-connector/troubleshooting/sign-in-unknown-host"><strong>Sign-in fails on an unknown host name</strong></a>: set <code>DS_MCP_PUBLIC_URL</code>.</td></tr><tr><td>The platform is on a private network</td><td><a href="https://docs.datasentinel.io/ai-connector/troubleshooting/private-network-mcp-servers"><strong>MCP servers on a private network</strong></a>.</td></tr><tr><td><code>datasentinel platforms</code> lists nothing</td><td>The server name misses the <code>datasentinel-</code> prefix, or the Skill is not in a folder the assistant reads. Ask the assistant to investigate its own MCP configuration.</td></tr><tr><td>Anything else</td><td>Every sign-in and tool call leaves a line in <a href="https://docs.datasentinel.io/ai-connector/troubleshooting/read-the-mcp-log"><strong>mcp.log</strong></a> on the platform host.</td></tr></tbody></table>

## Where to go next

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-server" style="color:$primary;">:server:</i></h4></td><td><strong>Install On-Premises and Configure Agentless Connections</strong>: the platform install this guide builds on.</td><td><a href="https://docs.datasentinel.io/manual/guides/readme/install-on-premises-and-agentless.md">Install On-Premises and Configure Agentless Connections</a></td></tr><tr><td><h4><i class="fa-rocket" style="color:$primary;">:rocket:</i></h4></td><td><strong>Onboard Your First PostgreSQL Cluster</strong>: get instances under monitoring so the assistant has data to reason over.</td><td><a href="https://docs.datasentinel.io/manual/guides/readme/onboard-your-first-cluster.md">Onboard Your First PostgreSQL Cluster</a></td></tr><tr><td><h4><i class="fa-users" style="color:$primary;">:users:</i></h4></td><td><strong>Manage Users and Role-Based Access</strong>: the profiles, privileges and roles the assistant inherits.</td><td><a href="https://docs.datasentinel.io/manual/guides/readme/manage-users-and-role-based-access.md">Manage Users and Role-Based Access</a></td></tr><tr><td><h4><i class="fa-file-pdf" style="color:$primary;">:file-pdf:</i></h4></td><td><strong>Generate, Email, and Schedule PDF Reports</strong>: the reports the assistant can request from the platform.</td><td><a href="https://docs.datasentinel.io/manual/guides/readme/pdf-reports.md">Generate, Email, and Schedule PDF Reports</a></td></tr></tbody></table>

## Conclusion

Enabling AI Connector is a short path: a platform at 2026.10 with the add-on in its licence, a health check that says `OK`, agents and the internal function for the richest metrics, and users whose profile and rights match what they should see. From there, each person registers the MCP server in their assistant, signs in once, installs the Skill, and starts asking questions in plain language. The assistant answers with findings ordered by impact and recommendations grounded in your own metrics, with the same read-only access and the same rights as the web interface.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.datasentinel.io/manual/guides/readme/connect-an-ai-assistant.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
