MCP server
Connect a compatible AI client to SwitchEffect’s built-in Model Context Protocol server, with explicit permissions for production and output control.
On this page
Connect a compatible client
- Open Settings → Automation in SwitchEffect. In the MCP section, turn on Enable MCP Server, then open Configure.
- For a client on another device, enable the trusted local-network or VPN interface you want under Network Access.
- Under Client Configuration, share the configuration for that interface and import its endpoint and authorization settings into your MCP client.
- Start with a read-only request, such as listing sources or checking switcher status. Grant additional control permissions only for the work you want that client to perform.
The client must support Streamable HTTP and bearer authorization. Configuration formats vary between clients; use the values exported by SwitchEffect rather than assuming a particular client’s JSON format.
Choose the right endpoint
The default port is 49994 and the path is /mcp. On the SwitchEffect device itself, the loopback endpoint is http://127.0.0.1:49994/mcp, unless you change the port.
127.0.0.1 always means the device running the client. A client on your Mac needs the iPhone or iPad’s enabled network endpoint from Client Configuration, not the loopback address.
Local-network and VPN interfaces are opt-in. SwitchEffect must remain running, and iOS may suspend it in the background. The server is not intended as an unattended, always-on service.
Choose what the client may do
| Permission | Available access |
|---|---|
| Pairing key only | Read status and list sources, macros, SuperScene presets, shows, and cues. |
| Allow Production Control | Assign Program or Preview, perform Cut or Auto, run macros, apply presets, load a show, and run a cue. |
| Allow Recording and Streaming | Start and stop recording or streaming independently of the production-control permission. |
View Only Mode has a separate MCP allowance under Settings → Automation → Allowed in View Only. Both that allowance and the relevant MCP permission must permit the action.
Client configurations contain the pairing key. Keep them private. Regenerate Pairing Key invalidates existing configurations, so reconnect clients using a newly exported configuration afterward.
Available tools
| Tool names | Purpose |
|---|---|
get_switcher_status, list_sources | Inspect the active switcher and available sources. |
list_macros, list_superscene_presets | Find saved production controls and layouts. |
list_shows, list_cues | Discover shows and their cues. |
set_program, set_preview | Assign a source directly to a bus. |
cut, auto | Transition from Preview to Program. |
run_macro, apply_superscene_preset | Run a saved macro or recall a layout. |
load_show, run_cue | Select a show and trigger a prepared cue. |
start_recording, stop_recording | Operate recording with output permission. |
start_streaming, stop_streaming | Operate streaming with output permission. |
Use the client’s discovered tool descriptions for parameters. Prefer references returned by the list tools over guessing names. Names must resolve unambiguously. set_program assigns Program directly; cut and auto are transition operations.
A useful first conversation
Example requests
“List the sources available in my current switcher.”
“Show me the cues in my interview show.”
“Set the guest camera on Preview. Leave Program unchanged.”
The first two are read-only tasks. The third needs Allow Production Control. Review the client’s proposed actions before using it to make live production changes. Recording and streaming destinations must already be configured in SwitchEffect.
If a client cannot connect
- Check that the server is enabled and the app is still running.
- Use the endpoint for an enabled interface reachable by the client. Check the port if you changed it.
- After regenerating the key, replace the client’s old configuration.
- A client that only supports local command-line/stdio servers needs its own compatible HTTP connection method. SwitchEffect provides a Streamable HTTP endpoint.
- If status works but an action fails, check production/output permissions, View Only Mode, the selected switcher, and whether the requested feature is available.