MQTT Studio

MCP integration

The MCP integration lets an AI agent build dashboards and query your data by chat. Point Claude Code, Codex, OpenCode, Claude Desktop, or any other MCP client at MQTT Studio, and you can ask it to set up a project, add widgets, read a sensor's history, and wire up automation rules, all in plain language.

The MCP integration is a Pro feature. Creating the API key it needs is also Pro tier.

#Create an API key

  1. Go to your account settings.
  2. Create a new API key.
  3. Copy the one-time secret.

The full secret starts with mqs_live_ and is shown only once, right after you create it. Copy it then and store it somewhere safe. If you lose it, create a new key.

#The endpoint

Your agent talks to MQTT Studio at a single endpoint:

POST https://mqtt.studio/api/v1/mcp

Authenticate with your API key as a Bearer token. Send it in the Authorization header:

Authorization: Bearer mqs_live_...

The endpoint speaks JSON-RPC 2.0 over HTTP, which is the MCP protocol. Most MCP clients handle the JSON-RPC details for you once you give them the URL and the token.

#Connect your MCP client

Every remote MCP client needs the same two things: the endpoint URL above and your API key in the Authorization header as a Bearer token. Replace mqs_live_... with the full secret you copied. Pick your client below.

#Claude Code

Add the server from your terminal:

claude mcp add --transport http mqtt-studio https://mqtt.studio/api/v1/mcp \
  --header "Authorization: Bearer mqs_live_..."

Add --scope project to share it with your team through a committed .mcp.json, or --scope user to use it across all your projects. Verify the connection with claude mcp list, or run /mcp inside a session. The entry it writes looks like this:

{
  "mcpServers": {
    "mqtt-studio": {
      "type": "http",
      "url": "https://mqtt.studio/api/v1/mcp",
      "headers": { "Authorization": "Bearer mqs_live_..." }
    }
  }
}

#Codex CLI

Add a server block to ~/.codex/config.toml:

[mcp_servers.mqtt_studio]
url = "https://mqtt.studio/api/v1/mcp"
http_headers = { "Authorization" = "Bearer mqs_live_..." }

To keep the secret out of the config file, read it from an environment variable instead:

[mcp_servers.mqtt_studio]
url = "https://mqtt.studio/api/v1/mcp"
bearer_token_env_var = "MQTT_STUDIO_TOKEN"

Then export it in your shell: export MQTT_STUDIO_TOKEN="mqs_live_...".

#OpenCode

Add a remote server to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mqtt-studio": {
      "type": "remote",
      "url": "https://mqtt.studio/api/v1/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer mqs_live_..." }
    }
  }
}

#Claude Desktop and other stdio-only clients

Some clients can only launch a local command and cannot reach a remote URL on their own. Bridge to MQTT Studio with mcp-remote. In Claude Desktop, edit claude_desktop_config.json:

{
  "mcpServers": {
    "mqtt-studio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mqtt.studio/api/v1/mcp",
        "--transport", "http-only",
        "--header", "Authorization: Bearer mqs_live_..."
      ]
    }
  }
}

Restart the client after saving the file. The same npx mcp-remote ... command works for any stdio-only MCP client.

#Other clients

Any client that supports remote MCP servers will work. Point it at https://mqtt.studio/api/v1/mcp and add the Authorization: Bearer mqs_live_... header. Field names differ between clients, but the URL and the header are all you need.

#What the agent can do

Once connected, the agent has these tools:

  • List, create, and update projects.
  • Set a project's broker: switch it to the included hosted broker, or point it at a custom external broker.
  • List, create, update, and delete widgets.
  • Read a widget's recorded history.
  • Manage automation rules: create, update, and list rules. A rule watches an MQTT topic, compares incoming values against a threshold, and when the comparison matches it runs actions. Actions can publish to a topic to control a relay (mqtt_publish) or send a Telegram alert.

#Example prompt

Paste something like this to your agent:

Create a project called Greenhouse, then build a temperature dashboard for it:
add a value widget reading the topic greenhouse/temp in Celsius, and a line
widget charting the same topic over time.

The agent creates the project and the widgets for you. From there you can keep going in plain language: add more widgets, ask it to read the recorded history, or set up a rule that sends a Telegram alert when the temperature climbs too high.

Still stuck? Contact us and we'll help you get set up.

View this page as Markdown