MCP

Connect an MCP client to Action Phrase

Action Phrase includes a built-in Model Context Protocol (MCP) server. Compatible AI assistants can use it to find saved phrases by meaning, inspect the variables they need, check the state of Action Phrase, and—with your permission—control the app or run a phrase.

The server uses MCP's Streamable HTTP transport. It runs inside Action Phrase, so there is no separate server, helper app, or command-line tool to install.

Phrase search is semantic and runs on-device. A client can ask for an outcome such as “focus the current camera on Camera 2” without knowing the exact saved phrase.

What an MCP client can do

After pairing, a client can:

• Find enabled, MCP-eligible phrases using a natural-language description.
• Inspect an exact phrase template, including its variables, tags, description, action types, and current availability.
• Check whether Action Phrase is listening.
• Inspect All Phrases, active groups, and saved groups.
• Start or stop listening and change the active phrase scope when Configure App via MCP is enabled.
• Run an exact saved phrase and receive a result for each action when Run Phrases via MCP is enabled.

MCP does not expose every action as an independent AI tool. Actions remain inside your saved phrases, preserving their configuration, variables, activation rules, order, and history.

Before you begin

You need:

• Action Phrase running on the device that stores your phrases.
• An MCP client that supports Streamable HTTP servers and authorization headers.
• Either a client on the same device or a connection over a trusted private network.

Set up the server

1. In Action Phrase, open Settings > Remote Control > MCP.
2. Turn on Enable MCP Server.
3. Under Network Access, leave only This Device available when the MCP client runs on the same device.
4. To connect from another device, select the specific private Wi-Fi, Ethernet, or VPN interface that device will use.
5. Leave the port at 49993 unless it conflicts with another service.
6. Open MCP Client Setup.
7. Enter a unique Client Configuration Name if the client will connect to more than one Action Phrase server.
8. Select the correct configuration interface, then choose Copy Configuration or Share Configuration.
9. Import the configuration into your MCP client.

Action Phrase generates a configuration using the commonly supported mcpServers JSON format:

{
  "mcpServers": {
    "action-phrase": {
      "url": "http://127.0.0.1:49993/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-PAIRING-KEY"
      },
      "enabled": true
    }
  }
}

Use the configuration generated by Action Phrase instead of copying this example. The generated version contains the current endpoint, configuration name, and pairing key.

The pairing key is a password. Do not publish it, paste it into support requests, or commit it to a repository.

Choose permissions

Pairing provides read-only access. Changing Action Phrase or running a phrase requires a separate permission.

Keep both optional permissions off until you need them.

Action Phrase does not show a separate approval prompt for every MCP request. Enabling a permission authorizes a paired client to use that capability. Use a client you trust and require it to show the exact change or phrase before it calls a tool that changes state.

Things you can ask

Phrase discovery and inspection are always available to a paired client:

• “Find a phrase that focuses the current camera on Camera 2.”
• “What phrase could start the presentation timer?”
• “What variables does that phrase need?”
• “Is Action Phrase listening?”
• “Which groups are active?”
• “Is All Phrases enabled?”
• “List my groups.”

With Configure App via MCP enabled:

• “Start listening.”
• “Enable the Cameras group.”
• “Make Cameras and Presentation the active groups.”
• “Turn on All Phrases.”

With Run Phrases via MCP enabled:

• “Run the phrase that starts the show timer.”
• “Execute the phrase for switching Videohub output 5 to input 6.”

How phrase execution works

A client should use this sequence:

1. Call find_phrases with the outcome you want.
2. Call get_phrase for the selected result.
3. Show the exact phrase and variable values for confirmation.
4. Call run_phrase only after you approve it.

The reference returned by find_phrases identifies the saved phrase. The client should pass that reference to get_phrase and run_phrase instead of trying to recreate it.

To run successfully, a phrase must:

• Still exist and be enabled.
• Be available to language-model matching.
• Be active in the current phrase scope, unless Action Phrase is configured to ignore activation gates for automations.
• Receive a non-empty value for every required ``.

Action Phrase runs one MCP-requested phrase at a time and returns the overall result plus the result of each action.

Available tools

Phrase tools

State and control tools

When All Phrases is enabled, it remains the active scope even if individual groups are selected. Disable All Phrases when you want group selection to control which phrases are active.

Network and security

Action Phrase always provides a loopback endpoint at 127.0.0.1. Use it when the client and Action Phrase run on the same device.

For another device on your local network, enable only the private interface you trust and use the configuration generated for that interface. Action Phrase can listen on eligible private Wi-Fi, Ethernet, and VPN addresses, including Tailscale-style addresses.

The MCP connection uses HTTP, not HTTPS. Never forward the MCP port through your router, expose it to the public internet, or use it on a shared or untrusted network.

For the safest setup:

• Prefer the This Device endpoint.
• Enable only the private network interfaces you need.
• Share the generated configuration only with the intended client.
• Regenerate the pairing key immediately if it may have been exposed.
• Review the privacy policy of your MCP client and AI provider. Action Phrase builds its semantic index on-device, but a paired client can read returned phrase information.

Regenerating the pairing key disconnects existing clients until their configuration is updated.

Background behavior on iPhone and iPad

iOS controls how long apps can run in the background. The MCP server is most reliable while Action Phrase is open or actively listening with the microphone.

Technical details

Tool results include both text and structured content. Tool-level failures are returned as MCP tool errors with an error code and a human-readable message.

Troubleshooting

The client cannot connect

• Confirm Enable MCP Server is on.
• Open MCP Client Setup and confirm the server status is Running.
• Copy a fresh configuration for the interface the client actually uses.
• If the port has changed, import the newly generated configuration.
• If the port is already in use, choose another port between 1024 and 65535.

The client reports an authentication error

The pairing key is missing or out of date. Copy the current configuration from MCP Client Setup. If you regenerated the key, every existing client must be updated.

A client on another device cannot connect

• Do not use 127.0.0.1 from another device; it refers to that device itself.
• Make sure both devices can reach the selected private Wi-Fi, Ethernet, or VPN interface.
• Enable that interface under Network Access, then copy its specific configuration.
• Check whether a firewall or VPN policy blocks the selected port.

A control tool is refused

Turn on Configure App via MCP in Action Phrase settings.

A phrase cannot run

• Turn on Run Phrases via MCP.
• Confirm the phrase is enabled and available to language-model matching.
• Make sure it is active in the current phrase scope.
• Provide a non-empty string for every required variable.
• Wait for any other MCP-requested phrase to finish.

Phrase search is temporarily unavailable

Action Phrase rebuilds its on-device semantic index after phrase data changes. Wait a moment and retry. If Action Phrase reports that semantic search is unavailable, the device cannot provide the on-device sentence embedding required by find_phrases.