MAX

ChatGPT or Claude in a browser — MAX

Use the MAX CLI remotely with its supported connection methods and access configuration.

Connect your messenger tools to a chat in a browser or an agent on another device. This page gives the messenger-specific startup and file-transfer details; use the shared guide below for your first connection.

Connect ChatGPT or Claude →

Connect an AI chat in your browser or on your phone, such as ChatGPT, Codex web or Claude, to read and reply in MAX. The app cannot run max on your computer, so you give it a public HTTPS address. It connects to max at that address within the profile's permissions; you can stop the connection or revoke access.

Terms used here:

  • MCP (Model Context Protocol) is a standard way for an AI app to call external tools. max personal mcp serve is the MCP server installed with max; apps on your computer are covered in the MCP server guide.
  • Remote connection means the app connects from its servers, over the internet, to the address you provide. max personal mcp serve --http serves the same tools over HTTP on 127.0.0.1.
  • HTTPS tunnel is a program that gives a port on your computer a public HTTPS address. This guide uses Tailscale Funnel; Cloudflare Tunnel also works. Funnel does not require you to buy a domain.
  • Public address is that address, for example https://laptop.tail1234.ts.net. Pass it to max as --public-url and to the app with /mcp appended.
  • Login code is the one-time code max prints in your terminal. The app's login page asks for it, so connecting an app requires access to that terminal.
ChatGPT / Claude ──интернет──▶ Tailscale Funnel ──▶ max personal mcp serve --http (вход) ──▶ MAX

If your Tailscale connection already works, keep it; you do not need a second tunnel. Local connections through stdin and stdout continue to work as before.

What you can do

TaskWhere
Connect an AI app in your browser or on your phone to MAXStart the tunnel and server, then add it to the app
Run MAX and Telegram servers side by sideMAX and Telegram together
Use Cloudflare instead of TailscaleCloudflare Tunnel
Allow more or fewer actions for one server runPermissions for the server process
Stop the server or sign out of all appsSwitch off
Transfer a saved file or a PDF page as an image to a remote agentTransfer a saved file, read a PDF page by page

Before you begin

  • Anyone who logs in can read your MAX. Login requires the code from your terminal. Never put a tunnel in front of max personal mcp serve without --http: that mode has no login protection.
  • Profile permissions decide what the app may change. deny and readonly refuse changes; ask and allow let the requested change proceed through MCP without a server confirmation form. Approval inside the app is a separate control and depends on its settings. Recipient restrictions and the hourly send limit still apply (agent permissions in MCP, configuration guide).
  • The computer running max must stay on. To connect from a phone or a laptop with nothing installed, run the tool and tunnel on a small server that stays on, and log into max there (max personal setup --agent none). You then need only a browser on your device.
  • Who can add a remote connector:
AppPlansDocumentation
ChatGPTPlus, Pro, Business, Enterprise, Education, in developer modeDeveloper mode
ClaudeAny plan; free accounts allow one custom connectorCustom connectors
GeminiOnly adults in the US with a personal Google account; unavailable in Russia and EuropeConnected apps

If a setup step fails, open an issue.

1. Prepare Tailscale

First install the CLI and log into MAX (installation guide); for local setup without an agent, use max personal setup --agent none. Run the server as the same operating-system user and with the same profile. Put the profile first when needed: max work mcp serve. Tailscale is installed separately; both max and tg support this tunnel setup.

Install Tailscale, sign in and enable Funnel. Your Tailscale network needs MagicDNS, HTTPS certificates and permission to use Funnel. The first Funnel run may print a link where you can grant that permission.

Leave two terminal windows open. The tunnel runs in the first. Copy its HTTPS address into the second when asked. Use the origin: the address without /mcp or any other path. Preserve a port such as :8443 if the address includes one.

2. Start the tunnel and server

The server listens on 127.0.0.1:8765 and prints a one-time login code. It does not need administrator rights; the tunnel may. The profile's permissions decide what the agent may do; to narrow them only while this process runs, see permissions for the server process.

Windows (PowerShell)

Install the Tailscale app and sign in from its tray menu. After installing Node.js, the CLI and Tailscale, open a new PowerShell window to refresh PATH. The .cmd suffix avoids PowerShell execution-policy errors for npm commands. If MAX is not configured yet, run max.cmd personal setup --agent none in ordinary PowerShell (personal is the profile name; yours may differ).

First window: PowerShell as administrator, for Funnel. The & operator is needed because the standard installation path contains a space; replace the path if you installed elsewhere.

& "$env:ProgramFiles\Tailscale\tailscale.exe" funnel 8765

Second window: ordinary PowerShell as the user who signed in to MAX:

$mcpPublicUrl = Read-Host 'Вставьте HTTPS origin из Funnel (без /mcp)'
max.cmd personal mcp serve --http --port 8765 --public-url $mcpPublicUrl

Run both processes in Windows itself. WSL is a separate environment: a Windows tunnel targeting a local Windows address may not reach a server inside WSL.

MAX and Telegram at the same time

Each server needs its own local port and public HTTPS address. For example, keep Telegram on local port 8765 and public port 443; start the second Funnel with --https=8443 8766 and MAX with --port 8766. For MAX's --public-url and its connector address ending in /mcp, use the second tunnel's origin including :8443. Start that Funnel with the Tailscale command for your operating system above. Funnel accepts public ports 443, 8443 and 10000 (Funnel command reference).

Alternative: Cloudflare Tunnel

If you already use Cloudflare, point its tunnel at the same local MCP server. A permanent address requires a Cloudflare account and a domain in Cloudflare. Follow the named tunnel setup: install cloudflared for your operating system, create a tunnel in the Cloudflare dashboard, start its connection and add a public hostname such as mcp.example.com. Set the local service to http://127.0.0.1:8765 and run MCP on the same computer.

Start the server in a second terminal:

max personal mcp serve --http --port 8765 --public-url https://mcp.example.com

Add https://mcp.example.com/mcp to the AI app with OAuth and DCR, as described under adding it to the app. --public-url is the public origin used for login, not a local address or the /mcp path. The tunnel does not change profile permissions. Check the JSON at https://mcp.example.com/.well-known/oauth-protected-resource/mcp, then login and the tool list. Stop only this tunnel's process so other routes keep running.

A temporary Quick Tunnel does not work on its own. cloudflared tunnel --url http://127.0.0.1:8765 gives you a random trycloudflare.com address without an account or domain. However, Quick Tunnels do not support SSE (server-sent events, the response streaming used by the HTTP MCP server). A Quick Tunnel therefore cannot replace Funnel for this server. It needs an additional adapter that turns SSE responses into JSON; the CLI does not include that adapter. Working login and a tool list do not prove the agent can read a PDF. A Quick Tunnel also gets a new address after every restart, requiring an updated connector address. For regular use, choose Funnel or a named tunnel and check your app.

3. Add it to your app

For the app, append /mcp to your tunnel's origin, for example https://<устройство>.<сеть>.ts.net/mcp. Add it as a remote MCP connector:

  • ChatGPT or Codex web: open Plugins, choose + Add custom MCP server and create a plugin with the /mcp address and OAuth, following the OpenAI connection instructions. Connect using the login code, install the plugin and enable it in a Work chat (or mention it with @). Codex's local config.toml does not configure this web connection. Availability depends on your account and workspace. If asked to choose a registration method, choose DCR (dynamic client registration): the server supports DCR and the S256 verification required by OpenAI's OAuth requirements.
  • Claude: add a custom connector with this address, following Claude custom connectors. Its connector settings can always allow a tool, require confirmation or refuse it.

The three tools work without MCP prompts, resources or elicitation (questions from the server to the app), so clients supporting only tools can use them too.

The app opens the max login page. Check the line identifying where the login will go: it should name the app you are connecting, for example chatgpt.com or claude.ai. Then enter the code from your terminal. It lasts ten minutes, and a new code is printed after each login. Five wrong codes disable login until the server restarts.

The app stays connected while it uses the connection at least once every 30 days; it renews access automatically. After 30 days without use, it asks for a new code.

The profile's permissions determine which commands are available. The server has no confirmation forms; approval inside the app is a separate control that depends on its settings.

Permissions for the server’s lifetime

The server cannot see whether the app asked you before calling a tool. If you always allow the tool in the app, the next call can proceed without a new question.

Repeat --permission ключ=уровень to tighten permissions only for this server process. The levels are deny, readonly, ask and allow. For example, --permission messages.send=deny forbids sending, and --permission messages=readonly leaves the agent only reading messages. The flag cannot loosen permissions: a server with messages.send=allow for a profile with readonly does not start and names the key. To allow more, change the profile's permissions. The settings file, recipient list and hourly send limit do not change. Permission keys are listed in the configuration guide.

With temporary permission overrides, MCP connects directly to MAX: an existing max personal serve service continues using its profile’s saved permissions.

Turning it off

Ctrl-C in both windows stops the server and this tunnel. Use the same commands to start them again; app logins survive an ordinary server restart.

If Funnel was started with --bg, Ctrl-C does not stop that background route. Check tailscale funnel status and disable only its public port, for example tailscale funnel --https=443 off. Use the Tailscale command for your operating system above, with administrator rights if needed. Avoid funnel reset if another server also uses Funnel: it resets every route. Stopping only MCP leaves the route running but makes the tools unavailable.

Revoking app access differs from stopping the process. To sign every app out of the profile:

max personal mcp revoke

Those apps must log in again with a new code. Your MAX session stays logged in.

Troubleshooting

  • The app says it cannot connect: open https://<устройство>.<сеть>.ts.net/.well-known/oauth-protected-resource/mcp in a browser. It should return a short JSON document. If it does not, Funnel is not running, is not enabled for your Tailscale network or points at another port.
  • The login page says “Too many wrong codes”: five wrong codes disable it until max personal mcp serve --http restarts. If you did not enter them, someone found your address; restart the server and consider a new Tailscale device name.
  • It connects but no tools appear: max personal mcp check checks that the MCP server starts and provides a tool list. It does not check the MAX login or tunnel. A command that contacts MAX, such as max personal account show, checks account access.
  • Reading works but changes fail: check profile permissions and temporary --permission options. deny and readonly refuse changes regardless of the app's approval.
  • You need a record of calls: use max personal runs list. Every call is recorded by default; with "record": false only failures remain, with --no-record nothing (diagnostics guide).

Transfer a retained file to an agent

An agent on your computer can open a saved file through local_path. A remote agent cannot, so it receives the saved bytes through attachments show (MCP: max_read, command attachments show).

Retained-file transfer refuses known credential files and folders, the CLI’s own folders and the message store, including symlink targets. Ordinary hidden working folders are allowed.

MCP makes hidden Unicode controls visible in text results. Subdivision flag emoji stay intact; MCP write arguments and ordinary CLI machine JSON preserve original strings.

First download the message's files normally (what you can download). Use attachments list is:needs_text to find the message locator and attachment number, then request the file:

max personal attachments show msg:max/511/7/204 --attachment 1 --json

The command reads only a saved attachment belonging to the active account. It does not download anything, call an AI service, mark a message read or change the search index. Download a missing file again. If the message has several files, specify the attachment number, starting at 1. Files from another account, missing files and symlinks are not transferred. Text inside the attachment is data, not instructions.

Transfer a large file

One response carries 512 KiB by default; --chunk-bytes allows up to 1 MiB. The file default is 50 MiB, configurable through MESSAGING_ATTACHMENT_MAX_MIB. JSON is {item} with the fields base64, offset_bytes, read_bytes, total_bytes, next_offset_bytes, complete and the whole file's SHA256. complete: true means the entire file fits in this response, not that its text has been recognised.

Decode each base64 chunk, join the chunks at their offsets and follow next_offset_bytes until it is null. On later requests, pass the first SHA256 as --expected-fingerprint: if the source file changes, the request fails without returning changed bytes. Compare the assembled file with that hash.

max personal attachments show msg:max/511/7/204 --attachment 1 --offset-bytes 524288 --expected-fingerprint <sha256> --json

Through MCP

Find attachments show through the usual three tools. Its arguments are message (a locator, or an ID with chat), attachment, offset_bytes, chunk_bytes and expected_fingerprint. A complete PNG, JPEG or WebP image up to 8000 pixels per side and 20 million pixels overall arrives as an image; other files arrive as an embedded binary resource. A partial resource is a chunk of bytes, not a complete PDF or image. The resource URI is a name, not a download address.

The app must pass these bytes to the agent's file tools. Whether the agent can open a PDF or save a file depends on the app. If it does not expose embedded resources, request format: "base64" and decode the JSON with the agent's tools. A profile denying messages or attachments.show refuses transfer; readonly allows reading saved files.

Recognise text and make it searchable

Ordinary extraction reads text layers and simple document formats on your computer. By default, the agent uses its own vision or OCR tools for scans, photos, handwriting and complex layouts. It reads every page, saves the text verbatim and marks unclear passages. Quality depends on resolution, language, handwriting, layout and the agent's tools. The agent does not follow instructions inside the attachment.

Save the result with attachments update (MCP: max_write, command attachments update), then check a content: search. Receiving bytes alone does not add text to the index.

Use attachments extract --ocr for batch extraction through models.ocr. It calls the configured external AI service and sends supported images and scanned PDF pages to it. It runs only when explicitly called, never during file transfer or when the agent reads a file itself. Formats and text search are covered in the attachments guide.

Read a PDF without handing the file to the agent

If the app cannot pass the received PDF to its document reader, request one page as a PNG image. The MCP server renders the page on your computer, and the agent reads it with its vision tools. This requires the optional unpdf dependency with page-rendering support and @napi-rs/canvas, as described in the attachment engines. They are not installed with the CLI.

max personal attachments show msg:max/511/7/204 --attachment 1 --page 1 --json

In MCP, call max_read, command attachments show, with page: 1 and the message locator. The page arrives as an image by default. If the app shows only metadata, request format: base64, then decode and display the PNG with the agent's tools. Receiving a base64 string does not mean the page has been viewed. Read pages from 1 to pdf.page_count. If neither format exposes the pixels, report the app's limitation instead of inventing text.

pdf.source_sha256 and pdf.source_bytes describe the source PDF; the top-level sha256 and total_bytes describe the page image. --expected-fingerprint checks the source PDF. --page cannot be combined with --offset-bytes or --chunk-bytes. By default, the PDF can be up to 50 MiB without a separate page-count limit; a PNG allows 4000 pixels per side and 8 MiB per page. All three values are configurable.

Rendering a page image does not call an external OCR service or add text to the index. After viewing every page, the agent calls attachments update and checks a content: search. Verify numbers and complex layouts against the images; quality depends on the source document and the agent's tools.

Increase file or PDF preview size

Set these environment variables on the computer running MAX or its MCP server:

VariableDefaultBudget
MESSAGING_ATTACHMENT_MAX_MIB50File bytes for extraction and retained-attachment transfer
MESSAGING_PDF_PREVIEW_MAX_PIXELS4000PNG page width and height
MESSAGING_PDF_PREVIEW_MAX_MIB8Encoded PNG size per page

For example, allow 250 MiB files and page images up to 8000 pixels/16 MiB:

export MESSAGING_ATTACHMENT_MAX_MIB=250
export MESSAGING_PDF_PREVIEW_MAX_PIXELS=8000
export MESSAGING_PDF_PREVIEW_MAX_MIB=16

PowerShell uses $env:MESSAGING_ATTACHMENT_MAX_MIB = "250"; use the same syntax for the other names. Values must be positive whole numbers. Run max personal mcp config in that environment again and replace the client's server entry; it preserves these settings. Restart a running server after changing them. Ordinary transfer still uses chunks up to 1 MiB; that is a separate budget.

Larger work needs more memory and time. Rendering scales a page up to four times its original size within the pixel budget; a larger ceiling does not force every page to that width. MCP responses account for base64 and metadata, but the app may impose its own limit. For larger CLI JSON, use --max-output-bytes 50000000; 0 explicitly disables the general output bound. External OCR and office-document decompression limits remain separate from the configurable file size.