Remote Access

Macuse runs a local HTTP server on your Mac. To use it with web-based AI tools like Claude.ai or other remote MCP clients, you need to make the server accessible over the internet.

A tunnel service creates a secure public URL that forwards traffic to your local Macuse server. This guide covers two options: Tailscale Funnel and Cloudflare Tunnel.

Option A: Tailscale Funnel

Tailscale Funnel is the simplest option. One command gives you a stable HTTPS URL.

Prerequisites

1. Install Tailscale on your Mac
2. Sign in to your Tailscale account
3. Enable Funnel for your account (see Tailscale Funnel docs)

Start the Tunnel

tailscale funnel 35729

Tailscale assigns a stable URL like:

https://your-machine.tail1234.ts.net

Your MCP endpoint is available at:

https://your-machine.tail1234.ts.net/mcp

Keep It Running

To run the tunnel in the background:

tailscale funnel --bg 35729

To stop the tunnel:

tailscale funnel --reset

Option B: Cloudflare Tunnel

Cloudflare Tunnel provides a free, stable URL with global CDN. It requires more setup but works well for long-term use.

Prerequisites

1. A Cloudflare account (free plan works)
2. Install cloudflared:

brew install cloudflare/cloudflare/cloudflared

Quick Start (Temporary URL)

For a quick test without a custom domain:

cloudflared tunnel --url http://127.0.0.1:35729

This gives you a temporary *.trycloudflare.com URL. The URL changes each time you restart.

Your MCP endpoint is available at:

https://random-name.trycloudflare.com/mcp

Permanent Setup (Custom Domain)

For a stable URL, set up a named tunnel with your own domain:

1. Authenticate with Cloudflare:

cloudflared tunnel login

2. Create a tunnel:

cloudflared tunnel create macuse

3. Point your domain to the tunnel:

cloudflared tunnel route dns macuse mcp.your-domain.com

4. Create a config file at ~/.cloudflared/config.yml:

tunnel: macuse
credentials-file: ~/.cloudflared/macuse.json

ingress:
  - hostname: mcp.your-domain.com
    service: http://127.0.0.1:35729
  - service: http_status:404

5. Start the tunnel:

cloudflared tunnel run macuse

Your MCP endpoint is now available at:

https://mcp.your-domain.com/mcp

Run as a System Service

To keep the tunnel running after closing the terminal:

sudo cloudflared service install

Which One Should I Use?

Connect from Web-Based AI Tools

Once your tunnel is running, use the public URL to connect from any MCP-compatible AI tool.

Claude.ai

1. Go to claude.ai and open Settings
2. Find the MCP or Integrations section
3. Add a new MCP server with your tunnel URL:

https://your-tunnel-url/mcp

4. Claude will initiate an OAuth authorization flow
5. Approve the connection in Macuse on your Mac

Other AI Tools

Any AI tool that supports remote MCP servers can connect using the same URL:

{
  "mcpServers": {
    "macuse": {
      "url": "https://your-tunnel-url/mcp"
    }
  }
}

Using Bearer Tokens

Some AI tools don't support OAuth. For these, use Bearer Token authentication:

1. Connect from your AI tool using the tunnel URL (without authentication)
2. After a few failed attempts, Macuse detects the client doesn't support OAuth
3. A popup appears in Macuse asking you to generate a token
4. Copy the token and configure your AI tool:

{
  "mcpServers": {
    "macuse": {
      "url": "https://your-tunnel-url/mcp",
      "headers": {
        "Authorization": "Bearer mcp_your_token_here"
      }
    }
  }
}

See Bearer Token Authentication for more details.

Security Notes

Tunnel services encrypt all traffic with HTTPS automatically. Combined with Macuse's built-in authentication, your server stays protected when exposed to the internet.

• Every new client needs approval. Remote users can't bypass the authorization step in Macuse.
• Revoke unused connections. Manage active connections in Macuse Settings → Connections.
• Custom port. If you changed the Macuse server port, use that port in your tunnel command instead of 35729.

Troubleshooting

Tunnel connects but AI tool gets errors

Make sure Macuse is running and the local server is active. Check the server status in the Macuse menu bar panel.

OAuth flow doesn't complete

The authorization popup appears in Macuse on your Mac. If you're away from your Mac, you won't be able to approve the connection. Consider using Bearer Tokens for unattended access.

Slow response times

Tunnel services add some latency. This is usually minimal (under 100ms) and shouldn't affect normal usage. If latency is a concern, choose a tunnel provider with servers close to your location.