# The Data Visions connector (MCP)

How the Data Visions MCP connector works: its address, adding it to Claude, Claude Code, Cursor, Codex or ChatGPT, sign-in, workspaces, changes and audit.

The **Data Visions connector** is an MCP server that you add to an AI app. Once connected, the app can look things up in your workspace, run reports, change records if you allow it and, for Workspace Admins, build and deploy modules. This page covers what a developer or a coding agent needs to know. For click-by-click steps in Claude and ChatGPT, see [Marketplace: Connect your AI](article:488b0b95-e1d0-453c-9f15-e0ce2a91d746).

## The connector address

Your workspace's connector address is shown in the app. A Workspace Admin gets it like this:

1. Open **System settings**, then **Marketplace**.
2. Click **Connect your AI** at the top.
3. Click **Copy** next to the address.

The address depends on the Data Visions installation you sign in at, so always copy it from this screen rather than typing one. Everyone in the workspace uses the same address and signs in as themselves. In the examples below, replace `<your connector address>` with the address you copied.

[Open the Marketplace now](/tenant/?open=settings/marketplace)

## Add it to your AI app

**Connect your AI** shows steps for Claude, Cursor, ChatGPT and Codex. In short:

| App | How to add it |
|---|---|
| **claude.ai or Claude Desktop** | **Settings › Connectors › Add custom connector**. Name it *Data Visions*, paste the address, leave the OAuth fields empty, then **Add** and **Connect**. In a new chat, turn on Data Visions from the tools menu. |
| **Claude Code** | Run the command below, then run `/mcp` and choose **Authenticate**. |
| **Cursor** | Add the server to `~/.cursor/mcp.json` (or your project's `.cursor/mcp.json`), then in **Cursor Settings › MCP** click **Needs login** next to *datavisions*. |
| **Codex** | **Settings › Plugins › MCPs › Add**, custom MCP. Name it *Data Visions*, choose **Streamable HTTP** (not STDIO), set the URL and leave the bearer token and headers empty. Then start the sign-in from the MCPs list; Codex does not open it by itself. |
| **ChatGPT** | Turn on **Developer mode**, then create an app with the address as the MCP server URL and Authentication set to **OAuth**. See [Marketplace: Connect your AI](article:488b0b95-e1d0-453c-9f15-e0ce2a91d746). |

Claude Code:

```
claude mcp add --transport http datavisions <your connector address>
```

Cursor (`mcp.json`):

```json
{"mcpServers": {"datavisions": {"url": "<your connector address>"}}}
```

Menu names can differ a little between versions of these apps.

## Sign in and allow

Every app connects the same way, with OAuth. You never paste a password, token or key into the AI app.

1. The app opens a Data Visions sign-in page. Sign in as yourself.
2. If you belong to several workspaces, pick the one to connect. If that workspace requires two-factor sign-in, enter your authenticator code.
3. The consent page lists what the app is asking for. Choose **Read only** or **Read and make changes**, then **Allow**.

After that the app stays connected without asking again for up to 90 days, unless the connection is disconnected or the workspace turns AI connectors off. To disconnect, remove the connector in your AI app's connector settings.

**A connection keeps the access it was first given.** If your workspace later allows changes, or your role gains more, disconnect and connect again to pick it up. The `whoami` tool tells you when a reconnect would give the connection more.

## What the AI acts as

- **You, and only you.** Every call runs as the person who connected, with that person's role and permissions in the workspace. The app can do nothing you can't do in Data Visions itself.
- **One workspace at a time.** The workspace comes from your sign-in, never from what the AI sends. No tool takes a workspace as an input, so the app cannot reach another workspace by asking.
- **Not a key holder.** The connector accepts only the sign-in made on the consent page. A personal access token or API key doesn't work here; tokens are for your own scripts.
- **The same rules as the app.** A module's own checks, permissions and refusals apply. Steps that need a person's approval in the app aren't offered to the AI app at all; finish them in Data Visions.

Ask the app "who am I and which workspace am I in?" at the start. It calls `whoami`, which returns your role, your permissions by module, what this connection may do and when its access expires.

## Several workspaces

If you belong to more than one workspace, for example because you build modules for several clients:

- `my_tenants` lists your workspaces, your type in each, which one the connection is working in now, and invitations waiting for you.
- `switch_tenant` moves the connection to another of your workspaces. Every later call works there, with your type and permissions there and that workspace's AI connectors setting, until you switch again.

A switch is refused if the other workspace has turned AI connectors off, or requires two-factor sign-in and you connected without it. In that case, disconnect, connect again with your authenticator code, and switch.

Coding agents: switch first, say so, and call `whoami` again before changing anything. Tools listed earlier can differ in the new workspace.

## Read only or make changes

Three things decide whether a connected app may change something: the workspace's **AI connectors** setting (under **System settings › Security**), the choice made on the consent page, and the person's role. What each kind of change needs:

| Change | Needs |
|---|---|
| **Create or change records** (module tools marked *(changes data)*, module actions, dashboards) | Workspace set to **Read and make changes**, **Read and make changes** chosen when connecting, and a role that allows it |
| **Save, share or delete your own reports** | Only reading: a report is a view of data you can already see. Your role's report permissions decide. |
| **Change websites** (save a version, publish, domains) | **Read and make changes** chosen when connecting, and your role's website permissions |
| **Build and deploy modules** (check in, deploy, submit) | Workspace Admin, and **Read and make changes** chosen when connecting |

When the workspace is **Off**, nothing works: every connection stops at once. Changing the setting applies to existing connections on their next call. See [Security: AI connectors](article:cc965b81-cdc0-4970-89ee-6ac862a413f2).

**Confirmations.** Every tool that changes something is marked that way to the AI app, so apps that support it ask you before each call. The connector also tells the AI to say exactly what will change and wait for a clear yes. Bulk changes go through a preview first: the AI shows you the whole change and applies it only after your yes. The connector also tells the AI to ask you before it deploys a module or submits one to the Marketplace.

## Built-in skills

Skills are written instructions the AI app reads before a task. The connector offers:

- **workspace-assistant**, for every user: how to start from what you can actually do, answer questions with numbers from your data, make changes safely, run bulk changes with a preview, and check the CLI before using it. The connector tells the AI to read it before anything beyond a single lookup.
- **Dashboard and report skills**: `dashboards-manage`, `chart-create`, `chart-edit`, `chart-reference` and `reports-design`.
- **Each module's own skills**, from the modules you can open.

The AI lists them with `module_skills` and reads one with `module_skill`. Workspace Admins also get the Module SDK through `sdk_doc`. See [The Module SDK: guides and references for coding agents](article:92da1335-5139-4bf1-8e35-dec5d5556947).

## Audit

Every tool call writes one entry to your workspace's audit log, whether it worked or not. The entry records who, which tool, which connected app, the outcome, how long it took and a short summary of the inputs, such as a module code or version. It never records file contents or the values you filtered on. Switching workspace is recorded too.

## For developers

- **Transport:** MCP over Streamable HTTP. The server is stateless: every request is answered with one JSON body, with no session and no server-to-client stream. Protocol versions 2025-11-25, 2025-06-18 and 2025-03-26 are supported.
- **Sign-in discovery:** a request without a valid sign-in gets a 401 that points the client at the sign-in server, so MCP clients find it by themselves. Leave OAuth client fields empty.
- **Tools you can't use are hidden.** The tool list contains only what your role and connection allow. Asking for more answers with an "insufficient scope" challenge, so the client can ask you to reconnect.
- **SDK as resources:** Workspace Admins can also read the SDK's Markdown files as MCP resources.
- **Result size:** a single module tool result is capped at 200,000 characters. Ask for less with a filter or a smaller limit.

For the full list of tools, see [Connector tool reference](article:eb4fdce8-03a5-4b28-85f2-6bf0ab76a3f1).

## Good to know

- **Only Workspace Admins see Connect your AI**, but anyone in the workspace can connect with the address.
- **Never give an AI app your password, authenticator code or token.** Sign-in always happens on the Data Visions page.
- **Large modules** (over 400 files or about 8 MB) are deployed with the CLI. See [Install and sign in to the CLI](article:9b9b3a9f-142d-4159-aae3-a9414adb33fc).
- **A tool you expected is missing?** Check your role, the workspace's AI connectors setting and what you chose when connecting. `whoami` shows all three.
- **To limit one person**, change what their role allows. Their AI app follows the same limits.


Source: https://datavisions.ai/docs/developer-tools/the-data-visions-connector-mcp
