voiceplays

An Alexa+ MCP add-on that runs your saved rote procedures by voice. Ask for something in your own words, it finds the matching procedure, starts it in the background and tells you how it went when you ask. Procedures that need arguments are refused by name. Procedures not tagged read-only are off unless you enable them, and even then need a confirmation code on a second turn. It is a self-hosted MCP server on Streamable HTTP, protocol version 2025-11-25, with OAuth 2.0 client_credentials for Alexa+.

Run it

Needs Node 22+ and rote with at least one saved play (rote play list).

npm install
export VOICEPLAYS_TOKEN=$(openssl rand -hex 32)
npm start

In a second terminal:

curl -s -X POST http://127.0.0.1:8787/mcp -H "Authorization: Bearer $VOICEPLAYS_TOKEN" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_procedure","arguments":{"phrase":"disk space"}}}'

Copy .env.example to .env to keep settings; npm start loads it.

Related MCP server: voxagent

Tools

Plays run 3s to several minutes, which no voice turn can wait for, so start and result are separate calls. A run past JOB_TIMEOUT_MS (15 minutes) is stopped along with every process it started.

Safety limits

• Auth on every request. A static bearer token for local use, OAuth client_credentials for Alexa+. The server refuses to start without one.

• Localhost by default with Host header validation always on, so a web page cannot reach it through DNS rebinding.

• Plays not tagged effect-read-only are refused unless listed in VOICEPLAYS_ALLOW_WRITES. Listed ones return a four-digit code first and run only when it comes back within two minutes. The code forces a second turn; it cannot prove a person spoke, so the allowlist is the real limit.

• Registry plays are refused unless listed in VOICEPLAYS_APPROVED_REGISTRY. rote asks for approval before running them, and a voice turn cannot answer, so listing a play is your standing approval and the server passes --yes for it only.

• Plays with required parameters are refused by name.

Alexa+ setup (not yet tested against Alexa+)

1. Expose the server over HTTPS, for example cloudflared tunnel --url http://127.0.0.1:8787.

2. Set PUBLIC_URL to that origin, plus VOICEPLAYS_CLIENT_ID and VOICEPLAYS_CLIENT_SECRET (openssl rand -hex 32).

3. Register PUBLIC_URL/mcp with the Alexa AI CLI, giving it the client ID and secret.

The server publishes /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, and issues one-hour tokens at /oauth/token for grant_type=client_credentials, scope mcp:service, resource=PUBLIC_URL/mcp. Issued tokens live in memory, so a restart makes Alexa+ fetch a new one.