Connect an AI assistant over MCP

Your workspace (the graph, tables, entity models, ingest, missions and your deployed APIs) is a Model Context Protocol server. Any client that speaks MCP over HTTP can use it, with a key you already have.

1.Endpoint

POST https://enqualia.io/api/mcp

The transport is Streamable HTTP: one JSON-RPC message per request, no session to keep open. A GET on the same address needs no key and says which server and protocol version answer, which makes a quick connectivity check:

curl https://enqualia.io/api/mcp

2.Which key

The key chooses the workspace. A key belongs to one project and reaches only that project, so there is no project parameter to get wrong. Send it as Authorization: Bearer <key>; X-API-KEY: <key> works too.

Key	What the assistant may do
Workspace key (read only)	Read the graph, tables, entity models, model cards and predictions. No writes, no spend, no mail.
Admin key (read and write)	Everything the workspace's own agent can do: write tables and documents, ingest, missions, storage, mail drafts, training, calling and building APIs. Tools that use models are billed. It is a full owner key: it also opens the admin API (deploying code, managing keys) and reads mail and connected documents, so revoke it once the assistant no longer needs it.

In your project, open Integrations and use Connect an AI assistant: it shows the endpoint, gives you the workspace key or creates an admin key for one assistant, and fills in the blocks below. An admin key made there is listed under API management, where you can revoke it at any time.

The tool list your assistant receives is what the key allows: tools outside the key's reach are left out of the list, and refused if called anyway.

3.Claude Code

claude mcp add --transport http enqualia https://enqualia.io/api/mcp \
  --header "Authorization: Bearer sk-your-key-here"

Add --scope user to have the server in every directory. claude mcp list shows whether it connected; claude mcp add --help shows the flags of your version.

4.Claude Desktop

Claude Desktop adds remote servers under Settings, Connectors, which expects an OAuth sign-in, and Enqualia uses a key. Use the small mcp-remote bridge in claude_desktop_config.json instead:

{
  "mcpServers": {
    "enqualia": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://enqualia.io/api/mcp",
        "--header",
        "Authorization:${ENQUALIA_KEY}"
      ],
      "env": {
        "ENQUALIA_KEY": "Bearer sk-your-key-here"
      }
    }
  }
}

The header has no space after the colon, and the whole Bearer sk-... value lives in the environment variable: on Windows a space inside an argument splits it in two. Quit Claude Desktop fully and start it again.

The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

5.Cursor

Put this in .cursor/mcp.json:

{
  "mcpServers": {
    "enqualia": {
      "url": "https://enqualia.io/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ENQUALIA_KEY}"
      }
    }
  }
}

Then set the key. On macOS or Linux, add this line to your shell profile (~/.zshrc or ~/.bashrc):

export ENQUALIA_KEY="sk-your-key-here"

On Windows, run this once in PowerShell or Command Prompt, then open a new window:

setx ENQUALIA_KEY "sk-your-key-here"

Use .cursor/mcp.json in your repository, or ~/.cursor/mcp.json for every project. The file only names the environment variable ENQUALIA_KEY, so it can be committed; the key itself goes in the environment Cursor starts from. Start Cursor again after setting it.

6.Codex

Put this in ~/.codex/config.toml:

[mcp_servers.enqualia]
url = "https://enqualia.io/api/mcp"
bearer_token_env_var = "ENQUALIA_KEY"

Then set the key. On macOS or Linux, add this line to your shell profile (~/.zshrc or ~/.bashrc):

export ENQUALIA_KEY="sk-your-key-here"

On Windows, run this once in PowerShell or Command Prompt, then open a new window:

setx ENQUALIA_KEY "sk-your-key-here"

bearer_token_env_var names an environment variable that holds the bare key (no Bearer in front); Codex sends it as a bearer token. Run codex mcp --help if your version rejects a key.

7.ChatGPT

ChatGPT's custom connectors sign in with OAuth and have no place for a key header, so ChatGPT cannot connect to an Enqualia workspace yet (October 2026). Use one of the clients above, or your own agent.

8.Your own agent

Post JSON-RPC 2.0 messages to the endpoint. Start with initialize, then use tools/list and tools/call:

curl -s https://enqualia.io/api/mcp \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",
       "params": {"protocolVersion": "2025-06-18", "capabilities": {},
                  "clientInfo": {"name": "my-agent", "version": "1.0"}}}'

curl -s https://enqualia.io/api/mcp \
  -H "Authorization: Bearer sk-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call",
       "params": {"name": "db_tables", "arguments": {}}}'

A tool's result is text inside content. For most tools that text is itself JSON, so you parse twice.

9.Long-running tools

Missions, ingests and training return a job_id at once and keep working. Poll the get_job tool until the status is succeeded or failed; cancel_job stops one. Some assistants poll on their own; if yours stops at the job id, ask it to keep polling.

10.Good to know

Mail is reachable only with an admin key, and only to read and to save drafts: there is no send tool.
Text from mail and from connected documents is someone else's writing. Your assistant should treat it as data, never as instructions.
Tool calls show up in your usage like the workspace's own agent; tools that use models are billed.
Calling your deployed APIs directly, without an assistant, is plain HTTPS: see Call your APIs.