MCP Server

gdotv includes an MCP server, so AI agents such as Claude Code, Cursor, Codex and VS Code, and chat clients such as claude.ai and ChatGPT, can work with every database you have connected to gdotv. MCP (Model Context Protocol) is the open standard these clients use to connect to tools.

Once connected, an agent can:

read your connections and their schemas, and write queries grounded in your real labels and properties;
run queries and hand you a link that opens the full result in gdotv;
work on the query tab you have open, changing it while you watch;
build dashboards and reports (saved queries with parameters) as private drafts, and publish them once you agree;
add new connections, testing them first.

The agent works through gdotv, never around it: your saved connections, your role and your connection settings decide what it can see and do.

This page covers setting up a client. Working with AI agents shows what to ask once it is connected, and the tool reference lists every tool the server offers.

Before you start

A gdotv licence or free trial. Most tools need one. Start a trial from Settings › Licence if you don't have one yet.
An MCP client. Any client that supports remote MCP servers over HTTP works. The setup screen has ready-made instructions for Claude Code, Cursor, VS Code, Codex, Gemini CLI, Windsurf, claude.ai and ChatGPT.
The server URL. Open Settings › MCP Server in gdotv: the URL is at the top of the page. It ends in /mcp, for example https://gdotv.example.com/mcp on a gdotv server.

How a client connects depends on which gdotv you use:

gdotv	How the agent signs in	Clients
gdotv Team or Enterprise, where you sign in with a gdotv account	With your gdotv account (OAuth). The first time the client connects, it opens your browser so you can sign in and approve it.	Coding agents, plus claude.ai and ChatGPT if your gdotv server is reachable from the internet
gdotv Desktop, or a gdotv server without sign-in	With an access token you generate in Settings › MCP Server, sent as an `Authorization: Bearer` header	Coding agents running on the same machine (Desktop) or able to reach the server

claude.ai, Claude Desktop and ChatGPT only accept remote servers that sign in with OAuth, so they cannot connect to gdotv Desktop. Use a coding agent such as Claude Code, Cursor or Codex with gdotv Desktop instead.

Set up a client (gdotv Team and Enterprise)

The quickest way is to let your agent configure itself. In Settings › MCP Server, copy the prompt under Tell your agent and paste it into your coding agent: it adds the server, starts the sign-in and lists the gdotv tools to confirm it works.

To set it up yourself, use the instructions for your client below, replacing the URL with yours. Each client opens your browser the first time it connects, so you can sign in with your gdotv account.

claude mcp add --transport http --scope user gdotv https://gdotv.example.com/mcp
# Then run /mcp in Claude Code, pick gdotv and choose Authenticate.

json

{
  "mcpServers": {
    "gdotv": { "url": "https://gdotv.example.com/mcp" }
  }
}

json

{
  "servers": {
    "gdotv": { "type": "http", "url": "https://gdotv.example.com/mcp" }
  }
}

codex mcp add gdotv --url https://gdotv.example.com/mcp
codex mcp login gdotv --oauth-client-registration dcr

json

{
  "mcpServers": {
    "gdotv": {
      "httpUrl": "https://gdotv.example.com/mcp",
      "oauth": { "enabled": true, "scopes": ["gdotv-mcp"] }
    }
  }
}

json

{
  "mcpServers": {
    "gdotv": { "serverUrl": "https://gdotv.example.com/mcp" }
  }
}

Notes by client:

Cursor: the Add to Cursor button in gdotv installs it in one click. Cursor then lists gdotv under Settings → Tools & MCP with "Needs login": click it to sign in.
VS Code: the Install in VS Code button in gdotv installs it in one click. Otherwise, add it to your user-level mcp.json (Command Palette: MCP: Open User Configuration). VS Code asks to authenticate when it starts the server.
Codex: if your Codex version has no --oauth-client-registration option, run codex mcp login gdotv on its own.
Gemini CLI: the configuration goes in ~/.gemini/settings.json. Keep the scopes line, which lets gdotv grant the access, then run /mcp auth gdotv in Gemini CLI.
Other clients: any client that supports MCP sign-in (OAuth 2.1 with PKCE) connects with the URL alone.

claude.ai and ChatGPT

Add a custom connector with your server URL:

claude.ai: Customize → Connectors → Add custom connector.
ChatGPT: Settings → Connectors, with developer mode on.

You are asked to sign in with your gdotv account and to approve the connection. If the sign-in stops on an error page, open the connector's advanced settings, choose automatic (dynamic) client registration instead of the app's published identity, and connect again.

These clients connect from their own cloud, so your gdotv server must be reachable from the internet for them to work.

The first time a client signs in, gdotv shows which client is asking for access and where it comes from: Verified when the client's identity was checked, or Registered from a site when the client registered itself. Only approve clients you set up yourself.

Set up a client (gdotv Desktop)

Open Settings › MCP Server and click Generate token. If you have no licence yet, this also starts your free 14-day gdotv trial, so your agent can query your databases straight away.
Copy the token straight away: gdotv shows it only once. You can always generate a new one.
Connect your client in one of three ways:
- Configure automatically: gdotv lists the clients it finds on your computer (Claude Code, Cursor, VS Code, Codex, Windsurf, Gemini CLI). Click Configure next to one to write the server and token into that client's configuration, then restart the client.
- Tell your agent: copy the prompt gdotv shows and paste it into your coding agent. It configures itself, keeping the token in an environment variable where the client supports it.
- Configure it yourself: click Prefer to configure it yourself? for the commands and configuration for each client.

For manual setup, put the token in an environment variable first, so commands can reference it instead of embedding it:

export GDOTV_MCP_TOKEN="gdotv_mcp_..."

Then add the server, using the URL from Settings › MCP Server:

claude mcp add --transport http --scope user gdotv http://127.0.0.1:PORT/mcp -H "Authorization: Bearer $GDOTV_MCP_TOKEN"

json

{
  "mcpServers": {
    "gdotv": {
      "url": "http://127.0.0.1:PORT/mcp",
      "headers": { "Authorization": "Bearer ${env:GDOTV_MCP_TOKEN}" }
    }
  }
}

json

{
  "servers": {
    "gdotv": {
      "type": "http",
      "url": "http://127.0.0.1:PORT/mcp",
      "headers": { "Authorization": "Bearer ${env:GDOTV_MCP_TOKEN}" }
    }
  }
}

codex mcp add gdotv --url http://127.0.0.1:PORT/mcp --bearer-token-env-var GDOTV_MCP_TOKEN

gemini mcp add --transport http --header "Authorization: Bearer $GDOTV_MCP_TOKEN" gdotv http://127.0.0.1:PORT/mcp

json

{
  "mcpServers": {
    "gdotv": {
      "serverUrl": "http://127.0.0.1:PORT/mcp",
      "headers": { "Authorization": "Bearer gdotv_mcp_..." }
    }
  }
}

Notes by client:

Claude Code: run the command in a shell where GDOTV_MCP_TOKEN is set. Claude Code stores the resolved header in its user configuration.
Cursor and VS Code: they read ${env:GDOTV_MCP_TOKEN} when they start, so launch them from a shell that has it set, or replace the placeholder with the token. The Add to Cursor and Install in VS Code buttons in gdotv do the setup in one click.
Codex: reads the token from GDOTV_MCP_TOKEN when it runs, so the token never lands in its config.toml.
Windsurf: has no environment variable substitution, so the token is written into its configuration as is.
Other clients: Zed, Cline, Roo Code, JetBrains Junie and most others accept a url plus headers in the common mcpServers shape.

The same steps apply to a gdotv server running without sign-in, using its URL instead.

Managing the token

Settings › MCP Server shows when the token was created and last used. The full token cannot be shown again.
Regenerate token stops the old token immediately. Every client that used it needs the new value.
Anyone with the token can run queries with your saved connections' privileges. Regenerate it if it leaks, for example if you pasted it into a chat whose history is later shared.

Check that it works

Ask your agent something simple:

List my gdotv connections.

The agent should answer with the connections you can see in gdotv. If it reports an error instead, see Troubleshooting.

What agents are allowed to do

Reading is the default

On every connection, agents can only run queries that gdotv can verify as reads. gdotv parses each query before it runs and refuses anything that writes data, anything it cannot parse, and dialects it cannot check. This is the same strict rule gdotv applies to read-only roles: when in doubt, the query is refused.

EXPLAIN only plans the query, and PROFILE runs it to measure it: both are allowed for a query gdotv verifies as a read.

Allowing writes on a connection

To let agents change data on a connection, edit the connection and switch on Allow writes through the MCP server. It is off by default, and only you can turn it on: agents cannot change it.

With it on, agents' queries run as written, so keep your client's tool confirmations on and check what the agent is about to run. If the connection has Enforce read-only switched on, no writes are allowed, whatever this setting says.

Your role still applies

On gdotv Team and Enterprise, an agent you sign in acts as you, with your roles. It sees the connections you can see and can only do what your role allows on each one. For example, a user with the Business role can browse a connection and run its published reports and dashboards, but cannot run queries of their own, through an agent or otherwise. Writes also need the manage-data permission, as they do in gdotv.

Agents can ask gdotv what your role allows on each connection before offering to do something, so they don't suggest work they would be refused.

What agents cannot do

Delete a published dashboard or report. Agents can discard their own drafts, and only after you confirm.
Turn on Allow writes through the MCP server, or change who has access to what.
Reach connections you don't have access to.

Security

Keep your client's tool confirmations on. Query results are data, and data can contain text written to look like instructions. If a property value tells the agent to do something, that was not you. gdotv tells agents to treat returned data as untrusted, but your confirmation is the last check.
Links are tied to your account. The links an agent gives you only open for the gdotv account they were made for, and they expire. Queries run from such a link are always read-only.
Agents' actions are audited. On gdotv Enterprise, everything an agent does is recorded in the Audit Trail under your name, marked MCP, with the name of the client.

Disconnecting a client

gdotv Team and Enterprise: remove the server or connector from the client. Access stops when it is removed, and changes to your roles apply straight away.
gdotv Desktop: click Regenerate token in Settings › MCP Server. Every client using the old token is disconnected.

Troubleshooting

Problem	What to do
The client reports Missing bearer token or Invalid bearer token	The token is missing, or was regenerated. Generate or regenerate it in Settings › MCP Server and update the client.
The client reports Sign-in required or Invalid or expired access token	Sign in again from the client (for example `/mcp` in Claude Code, then Authenticate).
The client tries to sign in, but gdotv uses a token	Remove the `Authorization` header and the token from the client's configuration for a gdotv Team or Enterprise server; add them for gdotv Desktop.
claude.ai or ChatGPT stops on an error page during sign-in	In the connector's advanced settings, choose automatic (dynamic) client registration and connect again.
claude.ai or ChatGPT cannot connect to gdotv Desktop	They only connect to servers on the internet that sign in with OAuth. Use a coding agent such as Claude Code, Cursor or Codex.
The agent says gdotv MCP requires a licence	Start a trial or add your licence in Settings › Licence, then ask again.
The agent says writes through MCP are disabled	Switch on Allow writes through the MCP server on the connection, if you want the agent to change data.
The agent says your gdotv role does not allow something	Ask a gdotv admin to change your access in Settings › Access Control.
The agent cannot see a connection	It only sees the connections you can see in gdotv. Check the connection is shared with you.
A link from the agent says it has expired	Ask the agent for a new one.

Working with AI agents: what to ask, dashboards, reports and your open query tab
MCP tool reference
Access Control
Audit Trail
AI Query Assistant, gdotv's built-in chat panel

MCP Server ​

Before you start ​

How agents sign in ​

Set up a client (gdotv Team and Enterprise) ​

claude.ai and ChatGPT ​

The consent screen ​

Set up a client (gdotv Desktop) ​

Managing the token ​

Check that it works ​

What agents are allowed to do ​

Reading is the default ​

Allowing writes on a connection ​

Your role still applies ​

What agents cannot do ​

Security ​

Disconnecting a client ​

Troubleshooting ​

Related ​

MCP Server

Before you start

How agents sign in

Set up a client (gdotv Team and Enterprise)

claude.ai and ChatGPT

The consent screen

Set up a client (gdotv Desktop)

Managing the token

Check that it works

What agents are allowed to do

Reading is the default

Allowing writes on a connection

Your role still applies

What agents cannot do

Security

Disconnecting a client

Troubleshooting

Related