TagoIO | MCP Server

Connect your AI assistant to your TagoIO devices, data, and platform resources — directly from your IDE or AI tool.

Features

• Remote Server: Connect instantly via https://mcp.ai.tago.io — no local setup required
• Device Management: Access device information, configurations, and real-time data
• Data Analysis: Perform statistical operations (sums, averages, reports) on stored data
• Platform Integration: Retrieve users, actions, analysis scripts, and account statistics
• Code Generation: AI-powered TagoIO Analysis script generation with proper context
• Development Support: Debug assistance and tag relationship analysis
• Dual Protocol Support: STDIO (default) and HTTP Streamable transport protocols

Quick Start

1. Get a token — Go to TagoIO Profile Settings and generate a Profile Token
2. Pick your setup — Remote Server (recommended) or Local Server
3. Configure your platform — Find your IDE or AI tool below and copy the config

Prerequisites

• TagoIO account with a valid Profile Token (generate one here)
• Node.js 22+ (download) — only required for the Local Server setup

Remote Server (Recommended)

Connect directly to the TagoIO hosted MCP server at https://mcp.ai.tago.io. No local installation or Node.js required.

Authentication is done via the Authorization header with your Profile Token.

Region: Requests default to US East (us-e1). To connect to a different region, add the x-tagoio-region header:

Header	Value
x-tagoio-region	eu-w1 (EU West)
x-tagoio-region	https://api.your-instance.tagoio.net (dedicated instance)

---

VS Code

Add to .vscode/mcp.json in your project (or User Settings for global access):

{
  "servers": {
    "@tago-io/mcp": {
      "type": "http",
      "url": "https://mcp.ai.tago.io",
      "headers": {
        "Authorization": "Bearer ${input:tagoToken}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tagoToken",
      "description": "TagoIO Profile Token",
      "password": true
    }
  ]
}

VS Code Insiders

Same configuration as VS Code. Add to .vscode/mcp.json or User Settings.

Claude Code

claude mcp add-json @tago-io/mcp '{"type":"http","url":"https://mcp.ai.tago.io","headers":{"Authorization":"Bearer YOUR-TAGOIO-TOKEN"}}'

Claude Desktop

Claude Desktop does not natively support HTTP transport. Use the mcp-remote bridge:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "@tago-io/mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.ai.tago.io",
        "--header",
        "Authorization: Bearer YOUR-TAGOIO-TOKEN"
      ]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "@tago-io/mcp": {
      "url": "https://mcp.ai.tago.io",
      "headers": {
        "Authorization": "Bearer YOUR-TAGOIO-TOKEN"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "@tago-io/mcp": {
      "serverUrl": "https://mcp.ai.tago.io",
      "headers": {
        "Authorization": "Bearer YOUR-TAGOIO-TOKEN"
      }
    }
  }
}

JetBrains IDEs

Go to Settings > Tools > AI Assistant > Model Context Protocol (MCP) and add a new server with this JSON:

{
  "servers": {
    "@tago-io/mcp": {
      "url": "https://mcp.ai.tago.io",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer YOUR-TAGOIO-TOKEN"
        }
      }
    }
  }
}

GitHub Copilot

Add to .vscode/mcp.json (VS Code) or configure via CLI:

{
  "servers": {
    "@tago-io/mcp": {
      "type": "http",
      "url": "https://mcp.ai.tago.io",
      "headers": {
        "Authorization": "Bearer ${input:tagoToken}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tagoToken",
      "description": "TagoIO Profile Token",
      "password": true
    }
  ]
}

Google Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "@tago-io/mcp": {
      "httpUrl": "https://mcp.ai.tago.io",
      "headers": {
        "Authorization": "Bearer YOUR-TAGOIO-TOKEN"
      }
    }
  }
}

Amazon Q CLI

Add to ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "@tago-io/mcp": {
      "url": "https://mcp.ai.tago.io",
      "headers": {
        "Authorization": "Bearer YOUR-TAGOIO-TOKEN"
      }
    }
  }
}

OpenAI Agents / ChatGPT

In the OpenAI Agent Builder or ChatGPT MCP settings:

• Server URL: https://mcp.ai.tago.io
• Protocol: Streamable HTTP
• Authentication: Add Authorization: Bearer YOUR-TAGOIO-TOKEN header

Warp

Warp does not natively support HTTP transport. Use the mcp-remote bridge.

Add to ~/.warp/mcp.json:

{
  "mcpServers": {
    "@tago-io/mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.ai.tago.io",
        "--header",
        "Authorization: Bearer YOUR-TAGOIO-TOKEN"
      ]
    }
  }
}

Kiro

Kiro does not natively support HTTP transport. Use the mcp-remote bridge.

Add to .kiro/mcp.json in your project root:

{
  "mcpServers": {
    "@tago-io/mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.ai.tago.io",
        "--header",
        "Authorization: Bearer YOUR-TAGOIO-TOKEN"
      ]
    }
  }
}

Local Server

Run the MCP server locally via npx. Useful for offline development, air-gapped environments, or custom setups.

Requires Node.js 22+ installed (download).

STDIO Transport (Default)

Best for desktop AI assistants and IDEs. Add this configuration to your platform's config file (see Configuration Paths):

{
  "mcpServers": {
    "@tago-io/mcp": {
      "command": "npx",
      "args": ["-y", "@tago-io/mcp-server"],
      "env": {
        "TAGOIO_TOKEN": "YOUR-TAGOIO-TOKEN"
      }
    }
  }
}

For Claude Code, use the CLI:

claude mcp add @tago-io/mcp-server -e TAGOIO_TOKEN=YOUR-TAGOIO-TOKEN -- npx -y @tago-io/mcp-server

For VS Code / GitHub Copilot, use the inputs pattern for secure token prompting:

{
  "servers": {
    "@tago-io/mcp": {
      "command": "npx",
      "args": ["-y", "@tago-io/mcp-server"],
      "env": {
        "TAGOIO_TOKEN": "${input:tagoToken}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tagoToken",
      "description": "TagoIO Profile Token",
      "password": true
    }
  ]
}

HTTP Streamable Transport

For web-based AI platforms or when you need multiple clients connecting simultaneously:

# Start on default port 3000
npx -y @tago-io/mcp-server http

# Or pick a custom port
MCP_PORT=8080 npx -y @tago-io/mcp-server http

Your server will be available at http://localhost:3000.

Authentication: Pass your TagoIO token in the Authorization header:

Authorization: Bearer YOUR-TAGOIO-TOKEN

In HTTP mode, each request carries its own token — no TAGOIO_TOKEN environment variable needed. Multiple clients with different credentials can connect at the same time.

Health check: GET /health returns the server name, version, and status.

Configuration Paths

Platform	Config File Path
VS Code / GitHub Copilot	.vscode/mcp.json or User Settings
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Claude Code	Managed via claude mcp add CLI
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
JetBrains IDEs	Settings > Tools > AI Assistant > MCP
Google Gemini CLI	~/.gemini/settings.json
Warp	~/.warp/mcp.json
Amazon Q CLI	~/.aws/amazonq/mcp.json
Kiro	.kiro/mcp.json (project-level)

Authentication

The MCP server accepts two types of TagoIO tokens:

• Profile Token (recommended for getting started): Go to TagoIO Profile Settings and generate a new token. This grants full access to your profile.
• Analysis Token (for restricted access): Go to Analysis > select your analysis > copy the token. Your analysis must be set to run "External". This limits the MCP server to only the resources the analysis can reach — ideal for production or shared environments where you want to control access via IAM.

Replace YOUR-TAGOIO-TOKEN in any configuration above with your chosen token.

API Endpoints

The server connects to these TagoIO regions:

• US East: https://api.us-e1.tago.io (default)
• EU West: https://api.eu-w1.tago.io

Dedicated TagoIO instances are also supported — pass your full API URL as the region value.

How to set the region:

Setup	Method
Remote Server	x-tagoio-region header (e.g., eu-w1 or full URL)
Local STDIO	TAGOIO_API environment variable (e.g., https://api.eu-w1.tago.io)
Local HTTP	x-tagoio-region header (same as Remote Server)

Troubleshooting

Connection Failed

• Check your Profile Token is valid at TagoIO Profile Settings
• Ensure correct API endpoint for your region
• For the remote server, verify https://mcp.ai.tago.io is reachable

Authentication Error

• Confirm your token has the necessary permissions
• Verify the token format — use Bearer YOUR-TOKEN in the Authorization header (HTTP) or the TAGOIO_TOKEN env var (STDIO)

Data Access Issues

• Check device permissions in your TagoIO account
• Ensure devices have recent data available

mcp-remote Bridge Issues

If using mcp-remote for Claude Desktop, Warp, or Kiro:

• Ensure Node.js 22+ is installed (required for npx)
• Check that mcp-remote can reach https://mcp.ai.tago.io
• Try running npx -y mcp-remote https://mcp.ai.tago.io --header "Authorization: Bearer YOUR-TOKEN" manually to verify connectivity

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Need Help? Visit the TagoIO Documentation or contact our support team.