Articles on: Integrations

Control PlayAbility with an AI Assistant Through MCP

The PlayAbility MCP server gives a compatible AI assistant a local set of tools for working with PlayAbility. Depending on the request, it can inspect and switch profiles, read mappings, import mappings, navigate the app, read or change supported settings, send controls, manage windows, and capture screenshots.


Before you start


  • Install Node.js 18 or later and make sure the node command is available.
  • Use an AI client that supports local MCP servers launched through standard input/output.
  • Keep PlayAbility running on the same computer as the AI client.
  • Only connect an AI client you trust. MCP tools can send keyboard, mouse, and gamepad input.


The PlayAbility MCP server connects locally to the desktop app through ws://127.0.0.1:13123.


Enable MCP in PlayAbility


  1. Open Connections.
  2. Select WebSocket & MCP.
  3. Turn on Enable MCP Server.
  4. Wait for the MCP Configuration section to appear.


Enabling MCP also enables the WebSocket server and Allow WebSocket Inputs. It leaves Allow WebSocket Outputs off.


Secure the connection


  1. In the WebSocket Settings section on the same page, keep Require authentication key on.
  2. Make sure an Authentication key is present.
  3. If needed, select Generate New Key.


When authentication is enabled, the configuration generated by PlayAbility includes the same key as PLAYABILITY_WS_KEY.


Add the generated configuration to the AI client


  1. In PlayAbility, locate MCP Configuration.
  2. Check whether it is labelled Production or Development.
  3. Select Copy.
  4. Open the MCP server configuration in your AI client.
  5. Merge the copied playability entry into its mcpServers object.
  6. Save the configuration.
  7. Fully restart or reload the AI client so it launches the new server.


Use the configuration PlayAbility generates rather than typing the server path yourself. It contains the correct installed path and, when required, the authentication key.


Verify the MCP connection


  1. Open the AI client's MCP or integrations page.
  2. Confirm that a server named playability is listed and connected.
  3. Start with a read-only request such as:
    • "List my PlayAbility profiles."
    • "Show the current PlayAbility page."
    • "Read the mappings in my active profile."
  5. Check that the returned profile or page matches the desktop app.


Ask the assistant to send an input or change a setting only after read-only tools work.


What an assistant can do


The bundled MCP server includes tools to:


  • List profiles and read current or named profile mappings.
  • Switch profiles and import or append mappings.
  • Navigate to PlayAbility pages and report the current page.
  • Read exposed settings and change the remotely writable subset.
  • Send gamepad, keyboard, mouse, cursor, or batched inputs.
  • List displays and windows, focus, move, or resize windows.
  • Capture screenshots.
  • Read basic PlayAbility connection information.


Some security-sensitive settings cannot be changed through MCP. Serial and HID output, WebSocket authentication, analytics, and Windows input muting must be changed in the PlayAbility interface.


Troubleshooting


The MCP server does not appear in the AI client


  • Confirm that the client supports local MCP servers.
  • Check that node --version reports Node.js 18 or later.
  • Copy the configuration from PlayAbility again and verify that it was added to the correct client configuration.
  • Restart the AI client completely.
  • Review the client's MCP log for an invalid JSON or missing-file error.


The server appears but cannot connect to PlayAbility


  • Keep PlayAbility running.
  • Confirm that Enable MCP Server remains on.
  • Make sure port 13123 is not being used by another application.
  • If you generated a new authentication key, copy the updated MCP configuration into the client and restart it.


A Development configuration cannot start


Development configuration is for a source checkout. Build the repository's mcp-server before using the generated Development path. Normal installed copies should show a Production configuration.


A tool is missing or denied


  • Reload the client after updating PlayAbility.
  • Ask the client to refresh its MCP tool list.
  • Change security-sensitive options directly in PlayAbility.


Safety


  • Treat PLAYABILITY_WS_KEY as a secret.
  • Review requests before allowing an assistant to type, click, move a pointer, or import mappings.
  • Begin with read-only tasks.
  • Keep Allow WebSocket Outputs off unless another integration specifically needs the broadcast stream.
  • Turn off Enable MCP Server when you no longer need AI access. Doing so immediately ends the MCP connection.
  • The connection is local-only in current builds. Do not expose port 13123 to the internet.



Updated on: 30/07/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!