arkushHelp

Work with an AI agent

Connect your AI agent

Arkush has no AI of its own. You bring your own agent: Claude Code, or any other assistant that supports MCP. Your agent writes the queries, adds the charts and arranges the canvas. It works on the same dashboards you open, under your account, and every change it makes is recorded under your name.

On arkush.app, the agent does not run a BigQuery query, because the server holds no warehouse access. It writes the query into a datasource, and you run it with Refresh in the Data panel. The agent then works from the rows of that refresh. It runs derived views and other work over the saved rows itself.

MCP is the open standard that assistants use to reach tools. claude.ai, Claude Desktop, Claude Code, ChatGPT, Codex, Cursor, Gemini CLI and VS Code all support MCP connections.

Before you start

Sign in to arkush. Your agent acts as you, so the connection needs your account. Without an account, you cannot connect an agent.

Your agent must support remote MCP servers over HTTP, with OAuth sign-in. Some clients offer custom connectors only on some plans, or only after an administrator of your account turns them on. Your client's own settings or documentation say what your plan allows.

The connection address

The address for agents on arkush.app is:

https://arkush.app/mcp

On an org install, the address is the web address of that server plus /mcp. The Connect-an-agent panel in the app shows the address of the server you use, with a Copy button. To open it, open the account menu at the top right and select Connect an agent. While agents are connected, this menu item reads Agents · N connected. Two more entries open the same panel: the Connect an AI agent step on an empty dashboard, which shows until you connect an agent, and the Connect an agent… button in the Help panel. The Help panel opens from Help, the last icon in the icon rail at the right edge of a dashboard.

Open the account menu, then select Connect an agent. With an agent connected, the entry reads Agents · 1 connected.

Add the connection in your agent

claude.ai and Claude Desktop

https://arkush.app/mcp
  1. In claude.ai or Claude Desktop, open Customize → Connectors.
  2. Select + Add, then Add custom connector.
  3. Paste the connection address.
  4. Confirm the new connector, and connect it.

On a Team or Enterprise plan, an owner adds the connector for everyone, under Organization settings → Connectors.

An arkush page opens in your browser. Continue with Approve the connection.

Claude Code

claude mcp add --transport http arkush https://arkush.app/mcp
  1. Run the command.
  2. In Claude Code, type /mcp.
  3. Select the arkush entry.
  4. Select the choice to authenticate.

An arkush page opens in your browser. Continue with Approve the connection.

ChatGPT

https://arkush.app/mcp
  1. Open Settings → Security and login.
  2. Turn on Developer mode.
  3. Open Plugins, and select +.
  4. Under Connection, paste the connection address.
  5. If ChatGPT asks how the plugin authenticates, choose OAuth.

An arkush page opens in your browser. Continue with Approve the connection.

Codex

codex mcp add arkush --url https://arkush.app/mcp
  1. Run the command.
  2. Run codex mcp login arkush.

An arkush page opens in your browser. Continue with Approve the connection.

Cursor

Add to Cursor

{ "mcpServers": { "arkush": { "url": "https://arkush.app/mcp" } } }
  1. Select Add to Cursor.
  2. To add the server by hand instead, open ~/.cursor/mcp.json, or .cursor/mcp.json in your project.
  3. Put the configuration in the file.
  4. If the file already lists other servers, add only the arkush entry, under mcpServers.
  5. Cursor asks you to sign in the first time it connects.

An arkush page opens in your browser. Continue with Approve the connection.

Gemini CLI

gemini mcp add --transport http arkush https://arkush.app/mcp
  1. Run the command.
  2. In Gemini CLI, run /mcp auth arkush.

An arkush page opens in your browser. Continue with Approve the connection.

VS Code

Add to VS Code

{ "servers": { "arkush": { "type": "http", "url": "https://arkush.app/mcp" } } }
  1. Select Add to VS Code.
  2. To add the server by hand instead, open .vscode/mcp.json in your project.
  3. Put the configuration in the file.
  4. If the file already lists other servers, add only the arkush entry, under servers.
  5. In Copilot Chat, start the server from the MCP list. VS Code asks you to sign in the first time Copilot uses the server.

An arkush page opens in your browser. Continue with Approve the connection.

Any other client

https://arkush.app/mcp
  1. In your client, add a remote MCP server over HTTP.
  2. Paste the connection address as the server address.
  3. If the client asks for an authentication method, choose OAuth.

An arkush page opens in your browser. Continue with Approve the connection.

Approve the connection

The first connection opens an arkush page in your browser.

  1. If the page asks you to sign in, sign in with the account you use on arkush.
  2. Read the page. It names the agent, your account, and the address that the page returns you to. The agent chooses its own name. If you do not recognize the address, select Cancel.
  3. Select Allow. The page returns you to the agent.
The approval page, titled 'Connect Claude Code?'. It says that Claude Code wants to connect as dana@example.com and will be able to read and edit dashboards as that account. It says that the agent chose its name itself, and that the page then sends you to a program on your own computer at 127.0.0.1:33418. Below are the Allow and Cancel buttons.
The approval page names the agent, your account, and the address that it returns you to.

From then on, the agent can act as you on arkush, and everything it changes is recorded under your account. To check the connection, ask the agent to list your dashboards. An account with no dashboards gets an empty list, which also means that the connection works. A connection that fails gives the agent an error instead. The agent also shows under Your connected agents in the Connect-an-agent panel. Cancel on the page connects nothing.

The panel shows the date that each approval expires. An approval lasts 30 days from the last time the agent renewed its access. An agent in use renews its access as it works, so its approval stays. If the agent does not connect for 30 days, the approval expires, and the next connection asks for a new approval.

The Connect an agent panel, with two parts marked by numbers. 1 marks the connection address with its Copy button. Below it are the setup steps for each agent client, the Claude app first. 2 marks the one entry under Your connected agents: Claude Code, with a Disconnect button, the date it connected and the date its approval expires.
The Connect-an-agent panel: (1) the connection address, (2) a connected agent, with the date its approval expires.

NOTE — The agent gets its own access tokens, which work on arkush only. The agent never gets the credential of the Google or GitHub account that you sign in with. It also never gets the Google connection that your browser uses to run BigQuery queries and read private sheets (see Query BigQuery with your own account).

Disconnect an agent

  1. Open the account menu and select Agents · N connected. While agents are connected, the Connect an agent item carries this label.
  2. Find the agent under Your connected agents.
  3. Select Disconnect and confirm.
Disconnect an agent, then confirm in the dialog.

The agent loses access at once. To connect it again, approve a new connection.