# Remote Access Setup

How to expose your local RemNote MCP Server to cloud-based services and remote connector flows.

## Overview

By default, the RemNote MCP Server binds to localhost (127.0.0.1) and is only accessible from your local machine.
To enable cloud-based AI services or Claude remote connectors to access your RemNote knowledge base, you need to
expose the HTTP MCP endpoint remotely.

For local Claude Desktop or Claude Cowork in the Claude Desktop app, prefer the bundled local MCPB extension when
desktop extensions are enabled. Remote access is still required for Claude web/mobile, cloud-hosted clients, ChatGPT
Apps, and managed Claude deployments where local MCPB is disabled or not applicable.

**Security Warning:** The methods described here provide **no authentication** by default and expose your RemNote access
to anyone with the URL. Of course, **you can configure authentication** and access controls with tools like ngrok,
Cloudflare or Tailscale.

Unless you configure authentication, use remote access only for:

- Local development and testing
- Short-term demonstrations
- Integration testing with cloud-based agents or remote connector flows

## Architecture

When using remote access, the architecture becomes:

```
Cloud agent or remote connector ↔ Tunnel (HTTPS) ↔ HTTP MCP Server :3001 (127.0.0.1)
                                                    ↕
                                                    WebSocket Server :3002 (127.0.0.1)
                                                    ↕
                                                    RemNote Plugin (Local)
```

**Critical Security:** The WebSocket server ALWAYS binds to localhost (127.0.0.1) and cannot be overridden. Only the
HTTP MCP endpoint is exposed via tunnel.

## Quick Setup with ngrok

ngrok is the recommended solution for development and testing.

### Prerequisites

- RemNote MCP server installed
- RemNote app running with RemNote Automation Bridge plugin installed
- ngrok account (free tier works for testing)

### Installation

**macOS (Homebrew):**
```bash
brew install ngrok
```

**Linux:** [ngrok on Linux](https://ngrok.com/docs/guides/device-gateway/linux)

**Windows:**
```bash
choco install ngrok
```

### Authentication

1. Sign up at [ngrok.com](https://ngrok.com) (free tier is sufficient)
2. Get your authtoken from
   [dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken)
3. Configure ngrok:

```bash
ngrok config add-authtoken YOUR_TOKEN_HERE
```

### Usage

**Step 1: Start the RemNote MCP Server**

Start the server normally (default localhost binding):

```bash
remnote-mcp-server
```

Expected output:
```
RemNote MCP Server v<version> listening { wsPort: 3002, httpPort: 3001 }
```

**Note:** ngrok tunnels to localhost, so the default 127.0.0.1 binding works perfectly. No special host configuration
is needed.

**Step 2: Start ngrok Tunnel**

In a separate terminal, start ngrok:

```bash
ngrok http 3001
```

ngrok will output:
```
Session Status online Account your-account (Plan: Free) Version 3.x.x Region United States (us) Latency - Web Interface
http://127.0.0.1:4040 Forwarding https://abc123.ngrok-free.app -> http://localhost:3001
```

Copy the HTTPS forwarding URL (for example, `https://abc123.ngrok-free.app`).

**Step 3: Configure your cloud client**

Set the MCP server URL to:

```text
https://abc123.ngrok-free.app/mcp
```

**Note:** The `/mcp` path is required.

### Testing

To test the exposed endpoint, use the curl command from the [Troubleshooting
Guide](troubleshooting.md#testing-the-mcp-http-endpoint), replacing `http://localhost:3001` with your ngrok HTTPS URL
(for example, `https://abc123.ngrok-free.app`).

Expected response: JSON with server capabilities and an `mcp-session-id` header.

Important: include the required `Accept: application/json, text/event-stream` header.

### ngrok Limitations

**Free Tier:**

- URL changes on every restart (random subdomain like `abc123.ngrok-free.app`)
- Session timeout after 2 hours of inactivity
- "ngrok Browser Warning" screen for first-time visitors

**Solution:** Upgrade to ngrok paid plan for:

- Static domains (for example, `remnote-mcp.ngrok.app`)
- Longer session durations
- No browser warning screen

**Security and privacy considerations:**

- No authentication by default: anyone with the URL can access your RemNote endpoint
- HTTPS terminates at ngrok
- Requests are visible in the ngrok dashboard

**Mitigation options:**

1. Use temporary URLs and rotate frequently
2. Monitor ngrok dashboard at `http://127.0.0.1:4040`
3. Stop the tunnel when not in use
4. Do not share URLs publicly
5. Optionally add ngrok traffic policy authentication
6. For OAuth-based gating, review ngrok OAuth traffic policy actions: [Traffic policy
   overview](https://ngrok.com/docs/traffic-policy/index#traffic-policy-overview), [OAuth
   action](https://ngrok.com/docs/traffic-policy/actions/oauth)

## Alternative Solutions

### Cloudflare Tunnel

Cloudflare Tunnel is a free alternative with optional identity and access controls.

- Docs: [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/)
- Signup: [try.cloudflare.com](https://try.cloudflare.com/)
- Optional: configure [Access
  policies](https://developers.cloudflare.com/cloudflare-one/access-controls/policies/policy-management/) for
  authentication and access control

### Tailscale

Tailscale Funnel can expose local services through your tailnet.

- Docs: [Tailscale Funnel](https://tailscale.com/docs/features/tailscale-funnel)
- Pricing: [Tailscale Personal](https://tailscale.com/pricing?plan=personal)
- Authentication using OAuth see [OAuth in the Tailscale API](https://tailscale.com/blog/oauth)

## When Do I Need 0.0.0.0?

You do **NOT** need to bind to 0.0.0.0 for ngrok or tunnel usage. These tools tunnel to localhost.

Bind to 0.0.0.0 only when:

- Deploying on a VPS/cloud server and accessing from outside that machine
- Running in Docker containers (container networking requires it)
- Accessing the server from other devices on your local network
- Using a reverse proxy that requires network-wide binding

For ngrok specifically, the server stays on 127.0.0.1 and ngrok tunnels to localhost:3001.

Example:
```bash
remnote-mcp-server --http-host 0.0.0.0
```

Security warning: this exposes the server to any device on your network.

## Troubleshooting

### Connection Refused

**Symptom:** `curl` or your cloud client fails with "connection refused"

1. Verify server is running: `lsof -i :3001`
2. Verify tunnel forwarding to port 3001 (for ngrok, check `http://127.0.0.1:4040`)
3. Test local endpoint first (see [Troubleshooting: Testing the MCP HTTP
   Endpoint](troubleshooting.md#testing-the-mcp-http-endpoint))

### RemNote Plugin Not Connecting

**Symptom:** Server starts but RemNote plugin won't connect

1. WebSocket must stay on localhost
2. Plugin must connect to `ws://127.0.0.1:3002` (never through tunnel)
3. Verify server logs show `wsHost: "127.0.0.1"`
4. Verify plugin WebSocket URL and auto-reconnect setting

### Tunnel URL Changes Every Restart

Expected on free tier. Options:

1. Use scripts/env vars to update client config
2. Upgrade to ngrok paid plan for static domains
3. Use labeled tunnels with ngrok config

### HTTPS Required

**Symptom:** Cloud client rejects HTTP URLs

Use the `https://` tunnel URL, not `http://`.

### Rate Limiting

If ngrok free-tier limits are hit:

- Reduce polling frequency
- Upgrade ngrok plan
- Batch requests where possible

## Security Best Practices

1. Use temporary URLs
2. Monitor tunnel access logs
3. Keep exposure windows short
4. Keep URLs private

## Related Documentation

- [Configuration Guide](configuration.md) - Configure MCP clients
- [Claude Desktop / Cowork Remote Connector Configuration](configuration-claude-desktop-cowork.md) - Anthropic remote
  connector setup
- [ChatGPT Configuration](configuration-chatgpt.md) - ChatGPT Apps setup steps
- [remnote-mcp-server Command Reference](remnote-mcp-server-command-reference.md) - Server configuration options
- [Troubleshooting](troubleshooting.md) - Common issues
- [Demo](../demo.md) - See remote access in action

## Need Help?

- [Troubleshooting Guide](troubleshooting.md) - Common issues and solutions
- [GitHub Issues](https://github.com/robert7/remnote-mcp-server/issues) - Report bugs or ask questions
