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

# Configuring Claude

> Connect Claude Desktop and Claude Code to the Datris MCP server

This page covers the client-side configuration for Anthropic's Claude products to talk to the Datris MCP server. For server-side details (architecture, transports, available tools), see [MCP Server (AI Agent Integration)](/mcp-server).

## Authentication

The MCP server is a transparent forwarder — it has no API key of its own. When auth is enabled, the client sends an `x-api-key` header on every session and the MCP server forwards that key to the Datris REST API on every tool call.

* **Single-tenant OSS with `USE_API_KEYS=false`** (default): no key needed. The snippets below work as-is.
* **Single-tenant OSS with `USE_API_KEYS=true`**: append `--header x-api-key:<your-key>` to the `args` array. Issue and rotate keys from **Configuration → API-Keys** in the UI — the value shown when you create a key is what your client sends.
* **Hosted / multi-tenant**: each tenant gets a key from the trial provisioning flow. Append `--header x-api-key:<your-key>` to the `args` array. That same key authenticates both the REST API and the MCP server for that tenant.

The Configuration UI's **Connect Your Agent** panel pre-generates these snippets — paste your API key into the field there and the `--header` flag gets added automatically.

## Configuring Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows), then quit and relaunch Claude Desktop.

### Recommended: mcp-remote bridge (Docker stack)

Run the bundled MCP server through the [mcp-remote](https://www.npmjs.com/package/mcp-remote) stdio bridge. It transparently reconnects when the server restarts and lets every desktop agent (Claude Desktop, Cursor, Claude Code) share one snippet shape:

```json theme={null}
{
    "mcpServers": {
        "datris": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:3000/sse",
                "--transport",
                "sse-only"
            ]
        }
    }
}
```

The underlying connection is SSE to port 3000, so sessions register with the Datris server and the **Agent Monitor** tab in the Datris UI shows live tool-call streaming. `--transport sse-only` pins the protocol so the bridge doesn't try its streamable-HTTP fallback.

Requires Node.js on your `PATH` (`brew install node`). On macOS, Claude Desktop is a GUI app and doesn't inherit your shell `PATH`, so use the full path to `npx` (e.g. `/opt/homebrew/bin/npx`) if `npx` alone doesn't resolve.

If your instance requires an API key (`USE_API_KEYS=true` or hosted), append two more args:

```json theme={null}
"args": [
    "-y", "mcp-remote", "http://localhost:3000/sse",
    "--transport", "sse-only",
    "--header", "x-api-key:<paste your Datris API key here>"
]
```

### Alternative: stdio via uvx (no Docker)

If you're not running the Docker stack — for example, you only want the MCP server and run the Datris API separately — use the PyPI package directly:

```json theme={null}
{
    "mcpServers": {
        "datris": {
            "command": "uvx",
            "args": ["datris-mcp-server"],
            "env": {
                "DATRIS_API_URL": "http://localhost:8080"
            }
        }
    }
}
```

Requires `uv` / `uvx` (`brew install uv`). On macOS, Claude Desktop is a GUI app and doesn't inherit your shell PATH, so use the full path to `uvx` (e.g. `/Users/you/.local/bin/uvx`) if `uvx` alone doesn't resolve.

<Note>
  The stdio transport has no header layer, so it can't carry an API key. If your Datris instance has `USE_API_KEYS=true`, use the mcp-remote option above instead. With `USE_API_KEYS=false` (single-tenant OSS default), stdio works fine but tool calls won't appear in the Agent Monitor tab.
</Note>

## Configuring Claude Code

Add to `.mcp.json` in your project root. The same two options apply.

### Recommended: mcp-remote bridge (Docker stack)

```json theme={null}
{
    "mcpServers": {
        "datris": {
            "command": "npx",
            "args": [
                "-y",
                "mcp-remote",
                "http://localhost:3000/sse",
                "--transport",
                "sse-only"
            ]
        }
    }
}
```

To add an API key (`USE_API_KEYS=true` or hosted), append `"--header", "x-api-key:<your-key>"` to the args array.

### Alternative: stdio via uvx (no Docker)

```json theme={null}
{
    "mcpServers": {
        "datris": {
            "command": "uvx",
            "args": ["datris-mcp-server"],
            "env": {
                "DATRIS_API_URL": "http://localhost:8080"
            }
        }
    }
}
```

## Talking to Claude

Once the MCP server is configured, just talk to Claude naturally. Claude sees every Datris tool and picks the right one based on your request.

### First prompts (empty Datris)

If you've just installed Datris and have no data yet, these prompts exercise the full create → query loop without needing files on hand. Watch the **Agent Monitor** tab in the Datris UI as you go — you'll see each tool call stream in real time.

**1. Confirm discovery works (returns empty, but proves the round-trip):**

> "List my Datris pipelines and tell me what's there."

**2. Have Claude generate sample data and ingest it:**

> "Generate 50 rows of sample stock price data (symbol, date, open, close, volume) and ingest it into PostgreSQL as a pipeline called `stock_prices`."

This single prompt exercises `create_pipeline` (with destination schema), the actual ingest, and several supporting tools — multiple tool calls light up the activity log.

**3. Query the data you just created:**

> "Show me the top 10 rows in `stock_prices` by volume."

**4. Add AI-generated data quality rules:**

> "Profile the `stock_prices` pipeline and suggest data quality rules I should add."

This exercises the AI/CodeGen path — Claude writes Python validators, Datris runs them locally.

**5. Read the pipeline configuration resource:**

> "Read the Datris pipeline configuration reference and summarize what destination types are supported."

Confirms Claude can pull MCP resources (not just tools) — useful to verify your client supports both.

For the RAG path, ingest the document **outside** the chat (see the warning below), then ask Claude to search it:

```bash theme={null}
# from your terminal
datris ingest annual-report.pdf --dest pgvector --pipeline reports
```

> "Search the `reports` pipeline for \[topic from the PDF]."

### Ingest data

> "Create a pipeline called stock\_prices and ingest this CSV into PostgreSQL"

> "Ingest this sales data into PostgreSQL and validate that all prices are positive"

<Warning>
  **Don't drag large local files into the chat to ingest them.** When you say "ingest this PDF" with a file attached, Claude has to base64-encode the bytes and pass them as a string argument to the `upload_data` tool — that string traverses the conversation context, and a 300KB PDF alone consumes \~90K tokens before any work happens. Conversations hit "too long to continue" almost immediately.

  Use the right tool for each shape of input:

  * **Local files** of any size — use the CLI: `datris ingest <file> --dest <destination>`. No LLM, no context cost.
  * **Files at a URL** (S3, MinIO, HTTPS) — ask Claude to create a Datris **tap** that fetches them. Bytes are pulled server-side; the agent only handles the URL.
  * **Small inline data** (a few rows of CSV, a JSON snippet, generated sample data) — fine to drop into the chat.

  The chat path is for *natural-language operations* (querying, profiling, pipeline management, search), not for funneling local-disk files through a remote conversation.
</Warning>

### Query data

> "Show me the top 10 stocks by volume from the stock\_prices table"

> "What's the average closing price for AAPL?"

> "How many orders were placed in March?"

### Search documents (RAG)

> "Search my financial documents for information about quarterly revenue"

> "What does the employee handbook say about the return policy?"

### Profile data

> "Profile this CSV file and tell me what validation rules I should add"

> "What does this data look like? Give me a summary"

### Manage pipelines

> "List all my pipelines"

> "Delete the test\_pipeline"

> "What's the status of the stock\_prices pipeline?"

### Explore databases

> "What tables are in my PostgreSQL database?"

> "Show me the columns in the orders table"

> "What vector collections do I have?"

### Health and diagnostics

> "Are all the backend services running?"

> "Check the health of the platform"

You can drag small inline files (a CSV with tens of rows, a short JSON snippet) directly into the chat for ingestion or profiling. For larger or binary files, use the CLI or a tap (see the warning above).