Connect Claude Code to Taufinity Studio

Connect Claude Code to your Taufinity Studio organisation in under a minute. After setup, Claude Code can query your dashboards, run BigQuery insights, send widget chat messages, and read knowledge files, all from the same conversation.

30-second TL;DR

1. Install the Taufinity CLI and run taufinity auth login.
2. Run taufinity mcp login --init --global.
3. Start a new Claude Code session and ask: "list my Taufinity sites".

Prerequisites

• Claude Code v0.4 or later. Check with claude --version.
• A Taufinity Studio account. Sign in and confirm your org via the org switcher.
• The taufinity CLI installed and signed in. See API Keys → CLI for installation.

taufinity version
taufinity auth login        # opens your browser for the device-code flow

Installation

Option 1: One-command install

taufinity mcp install --client claude-code

Behind the scenes, this writes the snippet below to your Claude Code config. If you prefer to do it manually, the snippet is reproduced under Manual install.

Config file location

• macOS: ~/.claude.json (user) or <project>/.mcp.json (project)
• Linux: ~/.claude.json (user) or <project>/.mcp.json (project)
• Windows: %USERPROFILE%\.claude.json (user) or <project>\.mcp.json (project)

Option 2: Manual install, paste this snippet

{
  "mcpServers": {
    "taufinity": {
      "type": "http",
      "url": "https://studio.taufinity.io/mcp",
      "headers": {
        "Authorization": "Bearer ${TAUFINITY_API_TOKEN}"
      }
    }
  }
}

Notes

• Claude Code reads ${ENV_VAR} substitutions at launch, export TAUFINITY_API_TOKEN before starting the session.

Verify it works

Verify it works

Restart Claude Code, then ask "list my Taufinity sites".

When the assistant uses the connection you'll see a tool-use indicator in the Claude Code session output.

Available tools

The Studio MCP server exposes ~70 tools across these groups:

Data & dashboards

Tool	Purpose
list_dashboards	List dashboards configured for your organization
query_dashboard	Fetch rows from a specific dashboard with optional date / group-by filters
list_data_sources	List BigQuery tables available for natural-language queries
query_insights	Plain-language question → validated SQL → read-only execution

Widget chat

Tool	Purpose
list_widgets	List widgets in your account
create_conversation	Open a new conversation on a widget
send_chat_message	Send a message and receive the AI response (full widget pipeline including RAG, content gates, playbooks)
get_conversation	Retrieve a full conversation
list_widget_conversations	List conversations for a widget

Knowledge base

Tool	Purpose
search_knowledge	Query the RAG vector index directly

Agents

Tool	Purpose
list_agent_archetypes	The six shapes an agent can take, with what each costs
create_agent	Create an agent from a goal in plain language. Always created switched off
list_agents	The organization's agents, with their state and ceilings
get_agent	One agent: what it does, what it may use, what it costs
start_agent	Run one now. Joins the run in progress if there already is one
update_agent	Turn the schedule on or off, change the cadence, rename
delete_agent	Remove the agent. Everything it produced is kept

Your existing agents also appear as tools of their own, named after the agent, so you can start one by name without listing anything first. Each carries what it does, what it costs at most, and the promise that starting one twice joins the first run rather than spending twice. Up to ten are surfaced this way, and the list refreshes when agents change.

Creating an agent through this surface reaches the same handlers, the same ceilings and the same approvals as creating one in Studio. See Agents.

Without the CLI

Don't want to install the taufinity binary? Add the server entry manually to ~/.claude/mcp.json:

{
  "mcpServers": {
    "taufinity-studio": {
      "type": "http",
      "url": "https://studio.taufinity.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TAUFINITY_TOKEN"
      }
    }
  }
}

Get your token from Studio → Settings → API Keys. When your token is rotated, update this file by hand.

For older Claude Code versions that only accept stdio transports, use the mcp-remote bridge (requires Node.js 18+):

{
  "mcpServers": {
    "taufinity": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://studio.taufinity.io/mcp",
               "--header", "Authorization: Bearer YOUR_TAUFINITY_TOKEN"]
    }
  }
}

Troubleshooting

Symptom	Cause	Fix
tools/list returns 401	Token expired or wrong	Re-run taufinity auth login, restart Claude Code
tools/list returns 403	Account lacks access to the targeted org	Run taufinity --site <slug> auth login
tools/list returns 429	Hit the per-IP rate limit (300/window)	Wait, then try again. If sustained, kill any runaway agent
Connection times out / SSE drops on a long call	Cloudflare idle-timeout	Re-issue the call. Studio is working on resumable streaming.
Tool returns trace_id: … and a generic error	Server-side error logged in audit trail	Send the trace_id to your Studio admin to investigate

FAQ

What data leaves my laptop? Only the prompts and tool arguments Claude Code sends. Claude Code itself never sees your raw data. Studio runs queries and returns results.

Where is the bearer token stored? In ~/.claude.json (user scope) or your project's .mcp.json. Tokens are revocable at Studio → Settings → API Keys.

How do I revoke access? Studio → Settings → API Keys → revoke the relevant key. Claude Code's next request returns 401.

See also

• Claude Desktop: same server, different shell launcher
• Cursor: Cursor's IDE chat with the same MCP server
• API Keys: full reference for keys, scopes, rotation
• Data Governance: the security model