io.github.tago-io/mcp-server

Official

by tago-io · TypeScript

Model Context Protocol server for TagoIO data and analytics

Access TagoIO data and analytics platform through MCP.

README.md13 KBView on GitHub

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

Get a token — Go to TagoIO Profile Settings and generate a Profile Token
Pick your setup — Remote Server (recommended) or Local Server
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):

json

{
  "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

bash

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

json

{
  "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:

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:

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:

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:

json

{
  "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:

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:

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:

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:

json

{
  "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):

json

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

For Claude Code, use the CLI:

bash

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:

json

{
  "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:

bash

# 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:

code

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.

Install

Configuration

Environment variables

TAGOIO_TOKENrequiredsecret

Your TagoIO Profile Token or Analysis Token

TAGOIO_API

Your API endpoint for the TagoIO. Defaults to https://api.us-e1.tago.io

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@tago-io/mcp-server@2.1.3"
      ],
      "env": {
        "TAGOIO_TOKEN": "<YOUR_TAGOIO_TOKEN>",
        "TAGOIO_API": "<YOUR_TAGOIO_API>"
      }
    }
  }
}