Taufinity Studio

Appearance

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.
bash
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 ​

ToolPurpose
list_dashboardsList dashboards configured for your organization
query_dashboardFetch rows from a specific dashboard with optional date / group-by filters
list_data_sourcesList BigQuery tables available for natural-language queries
query_insightsPlain-language question → validated SQL → read-only execution

Widget chat ​

ToolPurpose
list_widgetsList widgets in your account
create_conversationOpen a new conversation on a widget
send_chat_messageSend a message and receive the AI response (full widget pipeline including RAG, content gates, playbooks)
get_conversationRetrieve a full conversation
list_widget_conversationsList conversations for a widget

Knowledge base ​

ToolPurpose
search_knowledgeQuery the RAG vector index directly

Without the CLI ​

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

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+):

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

Troubleshooting ​

SymptomCauseFix
tools/list returns 401Token expired or wrongRe-run taufinity auth login, restart Claude Code
tools/list returns 403Account lacks access to the targeted orgRun taufinity --site <slug> auth login
tools/list returns 429Hit 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 callCloudflare idle-timeoutRe-issue the call. Studio is working on resumable streaming.
Tool returns trace_id: … and a generic errorServer-side error logged in audit trailSend 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 ​