Remote Access Configuration

Remote Access Configuration

VoiceMode can run as an HTTP server, enabling remote access from Claude Desktop, Claude Code, Claude.ai, and other MCP clients. This guide covers how to configure different clients to connect to a VoiceMode server.

Overview

The voicemode serve command starts VoiceMode as an HTTP server instead of the default stdio transport. This enables:

• Local network access - Connect from other machines on your network
• Cloud access - Connect from Claude.ai and Claude Cowork via Tailscale Funnel
• Multiple clients - Share one VoiceMode instance across devices

# Start the server (localhost only by default)
voicemode serve

# Server starts at http://127.0.0.1:8765/mcp

Quick Start

Local Development

For local development, start the server and connect from your client:

# Terminal 1: Start server
voicemode serve

# Server runs at http://127.0.0.1:8765/mcp

Then configure your client to connect (see client-specific sections below).

Remote Access (Same Network)

To allow connections from other devices on your network:

# Bind to all interfaces
voicemode serve --host 0.0.0.0

# Or allow specific IP ranges
voicemode serve --host 0.0.0.0 --allow-ip 192.168.1.0/24

Remote Access (Tailscale)

For connections over Tailscale:

# Allow Tailscale IP range
voicemode serve --host 0.0.0.0 --allow-tailscale

Client Configuration

Claude Desktop (via mcp-remote)

Claude Desktop uses stdio transport by default. To connect to a remote VoiceMode server, use mcp-remote as a bridge.

Setup

1. Start the VoiceMode server:

   voicemode serve
   

2. Add to Claude Desktop's MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "voicemode": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp"]
       }
     }
   }
   

3. Restart Claude Desktop.

Remote Server

For a remote server (e.g., on another machine):

{
  "mcpServers": {
    "voicemode": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://192.168.1.100:8765/mcp"]
    }
  }
}

With Authentication

If using token authentication:

{
  "mcpServers": {
    "voicemode": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:8765/mcp",
        "--header", "Authorization: Bearer your-secret-token"
      ]
    }
  }
}

Claude Code

Claude Code can connect to VoiceMode in two ways: direct stdio transport (recommended for local use) or HTTP transport for remote servers.

Local Setup (Recommended)

For local development, use stdio transport directly in .claude/mcp.json:

{
  "mcpServers": {
    "voicemode": {
      "command": "uvx",
      "args": ["voice-mode"]
    }
  }
}

This is simpler and doesn't require running a separate server.

Remote Server (Built-in HTTP Transport)

Claude Code has built-in HTTP transport support. To connect to a VoiceMode server:

# Add to current project (recommended)
claude mcp add --scope project --transport http voicemode http://127.0.0.1:8765/mcp

# Or add globally for all projects
claude mcp add --scope user --transport http voicemode http://127.0.0.1:8765/mcp

This creates a configuration like:

{
  "mcpServers": {
    "voicemode": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Remote Server (Legacy mcp-remote)

For older Claude Code versions, use mcp-remote:

{
  "mcpServers": {
    "voicemode": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://your-server:8765/mcp"]
    }
  }
}

With VoiceMode Plugin

If using the VoiceMode plugin for Claude Code, it automatically configures stdio transport. For remote access, disable the plugin and use the HTTP transport configuration above.

Claude.ai and Claude Cowork

Claude.ai and Claude Cowork can connect to MCP servers via custom connectors. This requires your VoiceMode server to be accessible from the internet.

⚠️ Experimental: The Claude.ai/Cowork integration via Tailscale Funnel is still being refined. The setup works but the workflow may change. Use with caution and expect updates.

Prerequisites

1. Public accessibility: Your server must be reachable from Anthropic's IP ranges
2. HTTPS: Production deployments should use HTTPS (via reverse proxy or Tailscale Funnel)
3. Authentication: Strongly recommended for internet-exposed servers

Setup with Tailscale Funnel

Tailscale Funnel exposes your local server to the internet with automatic HTTPS.

Tailscale Prerequisites:

1. Tailscale account: Sign up at tailscale.com if you don't have an account
2. Tailscale installed: The Tailscale client must be installed and running on your machine
3. Funnel enabled: Funnel requires explicit enablement in your Tailscale admin console:
   • Go to Tailscale Admin Console → Access Controls
   • Add "funnel" to your ACL policy to allow Funnel for your tailnet
   • See Tailscale Funnel documentation for details

Setup Steps:

1. Install and configure Tailscale:

   # macOS
   brew install tailscale
   
   # Start Tailscale
   sudo tailscale up
   

2. Enable Funnel for your machine:

   # Enable Funnel (requires Tailscale admin approval)
   tailscale funnel 8765
   

3. Start VoiceMode with Anthropic IP allowlist:

   # Allow Anthropic's outbound IPs
   voicemode serve --allow-anthropic --secret your-secret-uuid
   

4. In Claude.ai settings, add a custom MCP connector:

   • URL: https://your-machine.tail12345.ts.net/mcp/your-secret-uuid
   • Name: VoiceMode

Direct Setup (No Tailscale)

If you have a public IP and domain:

1. Set up a reverse proxy (nginx, Caddy) with HTTPS

2. Configure the proxy to forward to localhost:8765

3. Start VoiceMode:

   voicemode serve --allow-anthropic --token your-secret-token
   

4. Add the custom connector in Claude.ai with your domain.

Anthropic IP Ranges

The --allow-anthropic flag adds Anthropic's outbound IP ranges (160.79.104.0/21) to the allowlist. This is required for Claude.ai and Claude Cowork connections.

Security Considerations for Tailscale Funnel

⚠️ Important: Tailscale Funnel exposes your local service to the public internet. While Tailscale provides the HTTPS layer, you are responsible for application-level security.

Recommendations:

1. Always use authentication: Never expose VoiceMode without --secret or --token
2. Use IP allowlists: Combine --allow-anthropic with authentication for defense in depth
3. Monitor access: Enable --log-level debug initially to monitor connection attempts
4. Rotate secrets: Change your --secret UUID periodically, especially if you suspect compromise
5. Disable when not needed: Stop the Funnel (tailscale funnel off) when not actively using Claude.ai

What Funnel exposes:

• Your VoiceMode MCP endpoint becomes publicly accessible via HTTPS
• Anyone with your Tailscale hostname can attempt connections
• IP allowlists (--allow-anthropic) prevent unauthorized access but require proper configuration

Security Best Practices

Defense in Depth

Combine multiple security layers:

# IP allowlist + token authentication
voicemode serve --allow-anthropic --token your-secret-token

# IP allowlist + URL secret
voicemode serve --allow-anthropic --secret your-secret-uuid

Authentication Options

Generating Secrets

# Generate a random UUID for --secret
uuidgen

# Generate a random token
openssl rand -hex 32

Network Security

1. Default binding: Server binds to 127.0.0.1 by default (localhost only)
2. Explicit allowlists: Use --allow-ip for specific ranges
3. Tailscale: Use --allow-tailscale for Tailscale-only access
4. No public binding: Avoid --host 0.0.0.0 without IP restrictions

Token Management

• Use environment variables for tokens in scripts
• Rotate tokens periodically
• Never commit tokens to version control
• Use different tokens for different clients

# Use environment variable
export VOICEMODE_TOKEN="your-secret-token"
voicemode serve --allow-anthropic --token "$VOICEMODE_TOKEN"

Transport Options

VoiceMode supports two HTTP transports:

Streamable HTTP (Recommended)

The default and recommended transport:

voicemode serve --transport streamable-http
# Endpoint: http://127.0.0.1:8765/mcp

• Better performance and reliability
• Supports bidirectional streaming
• Modern MCP transport standard

SSE (Legacy)

Server-Sent Events transport for backward compatibility:

voicemode serve --transport sse
# Endpoint: http://127.0.0.1:8765/sse

• One-way server-to-client streaming
• Shows deprecation warning
• Consider migrating to streamable-http

Troubleshooting

Connection Refused

Symptom: Client cannot connect to the server.

Solutions:

1. Verify server is running: curl http://127.0.0.1:8765/mcp
2. Check firewall settings
3. Verify correct host/port in client config
4. Enable debug logging: voicemode serve --log-level debug

401 Unauthorized

Symptom: Server rejects requests with 401.

Solutions:

1. Verify token is correct in client config
2. Check for typos in Authorization header
3. Ensure token matches server --token value

403 Forbidden

Symptom: Server rejects requests with 403.

Solutions:

1. Client IP not in allowlist
2. Add appropriate --allow-* flag or --allow-ip
3. Check client's actual IP (may differ behind NAT)

404 Not Found

Symptom: Server returns 404 for endpoint.

Solutions:

1. Check endpoint path matches transport (/mcp vs /sse)
2. If using --secret, verify secret is in URL path
3. Verify server transport matches client expectation

Tailscale Funnel Not Working

Symptom: Cannot access server via Tailscale Funnel URL.

Solutions:

1. Verify Funnel is enabled: tailscale funnel status
2. Check Funnel is allowed in Tailscale admin console (ACL policy must include "funnel")
3. Ensure correct port: tailscale funnel 8765
4. Wait a few minutes for DNS propagation
5. Verify Tailscale is connected: tailscale status
6. Check your Funnel URL format: https://<machine-name>.<tailnet-name>.ts.net

Diagnostic commands:

# Check Tailscale status
tailscale status

# Check Funnel configuration
tailscale funnel status

# Test local endpoint first
curl http://127.0.0.1:8765/mcp

# Test Funnel endpoint (replace with your URL)
curl https://your-machine.tail12345.ts.net/mcp

Claude.ai Cannot Connect

Symptom: Claude.ai custom connector fails.

Solutions:

1. Verify --allow-anthropic flag is set
2. Confirm server is accessible via HTTPS
3. Test URL in browser first
4. Check Tailscale Funnel status if using
5. Verify secret/token in connector URL

Voice Services Not Available

Symptom: VoiceMode connects but voice tools fail.

Solutions:

1. Ensure Whisper and Kokoro services are running on the server
2. Check service status: voicemode whisper status and voicemode kokoro status
3. Services must run on the same machine as voicemode serve

Environment Variables

Server behavior can be configured via environment variables:

# Default transport
export VOICEMODE_SERVE_TRANSPORT=streamable-http

# Default port
export VOICEMODE_SERVE_PORT=8765

# Default host
export VOICEMODE_SERVE_HOST=127.0.0.1

CLI options take precedence over environment variables.

See Also

• CLI Reference - Complete serve command documentation
• Configuration Guide - VoiceMode configuration options
• Claude Code Plugin - Plugin installation for Claude Code
• Tailscale Funnel documentation - Official Tailscale Funnel setup guide