MCP

Let AI assistants read, configure and run a Tangle project through the Model Context Protocol, with show protection.

tangle-core includes an MCP (Model Context Protocol) server, so an AI assistant can read a project, build rooms and cue lists, control devices and check monitoring. Every tool goes through the same command layer as the REST API: the same validation, scopes and audit log, plus a protection that keeps assistants away from a running show.

#Two ways to connect

Both need a running tangle-core and an API token. Create a token for the assistant on the machine that runs tangle-core:

tangle-core token create --name claude --scopes read,control,configure

The secret is printed once. Choose the scopes for what the assistant should be able to do (see Scopes).

Note: MCP access is part of Tangle Pro and Ultimate (and the demo mode). On other editions, MCP requests get 403 not_licensed. See Licensing.

#Streamable HTTP

Send the token as a bearer token on every request:

POST /mcp HTTP/1.1
Host: 127.0.0.1:7340
Authorization: Bearer tgl_...
Accept: application/json, text/event-stream
Content-Type: application/json

A request without a valid token gets 401 with a problem-details body. Unless tangle-core runs with --allow-remote, the MCP endpoint accepts only requests addressed to this machine (a loopback Host).

#stdio bridge

tangle-core mcp reads JSON-RPC messages from stdin, forwards each one to the running core's /mcp endpoint, and writes every answer and notification to stdout.

TANGLE_TOKEN=tgl_... tangle-core mcp
tangle-core mcp --url http://10.0.0.5:7340 --token tgl_...

If the core cannot be reached, the bridge answers each request with a JSON-RPC error that says so. When stdin closes, the bridge ends its MCP session and exits.

#Configure an assistant

Most desktop assistants read a JSON file that lists MCP servers. Add Tangle with the bridge:

{
  "mcpServers": {
    "tangle": {
      "command": "tangle-core",
      "args": ["mcp"],
      "env": { "TANGLE_TOKEN": "tgl_..." }
    }
  }
}

• If tangle-core is not on the assistant's PATH, give its full path in command.
• To reach a core on another machine, add "--url", "http://10.0.0.5:7340" to args. That core must run with remote access (--listen 0.0.0.0:7340 --allow-remote --insecure-http, see CLI).
• Restart the assistant after editing its configuration.

The server introduces itself as tangle-core and gives the assistant these instructions: read the project with get_project and live state with get_snapshot; change the configuration with the create_*, update_* and delete tools (dry run first); make things happen with send_intent; drive shows with control_timeline; never interrupt a running show without being asked.

#Scopes

Each tool needs one scope (shown in its description, which the assistant reads).

The tables below give each tool's scope.

Resources and live updates need read.

#Show protection

While any timeline is playing, an assistant whose token lacks the live scope cannot change anything. Every tool that edits the project, sends an intent, drives a timeline or runs an automation is refused with code show_running:

{
  "type": "https://tangle.dev/problems/show_running",
  "title": "Conflict",
  "status": 409,
  "detail": "the show is running (timeline main-show is playing); nothing was changed",
  "code": "show_running"
}

Reading always works. Give a token live only when an assistant should act during a show:

tangle-core token create --name show-assistant --scopes read,control,live

Other protections apply to every client, with or without live:

• Live timelines: editing a timeline (or its tracks and cues) while it plays is refused (timeline_running) unless the tool call sets allowLive: true.
• Network scans: discover_devices is refused while a timeline plays (show_mode).
• Deleting: delete only previews unless confirm is true.
• Redundancy: on a backup node, changes and control are refused with not_primary.

#Results and errors

Tool results are JSON (structured content). A list is wrapped as { "result": [...] }. When a tool fails, the result is an error whose content is a problem-details object with a stable code, detail and, for validation errors, errors listing each problem. The codes are the REST API's (see REST API errors); an unknown tool name gets unknown_tool.

Configuration tools (create_*, update_*, delete) return:

#Tools

#Project and configuration

kind for list, get and delete is one of: room, device, scene, timeline, track, cue, automation, alertRule, notificationChannel, maintenanceWindow, probe. Tracks need timelineId; cues need timelineId and trackId.

The create and update tools exist for every resource type; their input schema is the contract type, so the assistant sees every field:

The fields of each type are in Project file. dryRun: true validates and returns the changes without applying them. Device settings are checked against the module's settings schema, and secret settings go to the OS credential store.

#Project library

#Control and live state

Intents sent over MCP are recorded with source api and the token name. See REST API intents for intent names and targets.

#Dashboards

create_dashboard and update_dashboard publish directly. See Dashboards.

#Automations

#Listeners

#Device creator and community

#Cluster

#Maps, plans and images

#Lighting

#Monitoring (Sentinel)

Monitoring is part of Tangle Pro and Ultimate. See Sentinel.

#License

#Resources

All resources are application/json. The two {...} forms are also offered as resource templates.

Assistants can subscribe to resources to be notified when they change:

#Prompts

#Audit

Every change and control action made through MCP is recorded in audit.log (in the Tangle log folder) with surface mcp and the token name, like any other client. Use one token per assistant so the log shows who did what.