MCP Setup for Claude Desktop

One-click install via the bundled .mcpb extension. After this, a Claude Desktop chat can read your tiletopia panes, send commands, spawn new panes, etc. — subject to the policy you configure (see MCP Policy Guide).

Prerequisites

tiletopia ≥ 0.2.x installed and running (Releases)
Claude Desktop installed
Node 18+ on your PATH (the bundle wrapper uses npx mcp-remote; check with node --version in PowerShell)
The tiletopia MCP server enabled once so the per-install bearer token is written to %APPDATA%

Steps

1. Start the MCP server in tiletopia

Click the 🤖 button in the tiletopia titlebar
In the Config tab, click Server: ON
The panel shows a URL like http://127.0.0.1:47821/mcp and a bearer token. You don't need to copy them — the .mcpb reads them automatically.

2. Download the `.mcpb` bundle

In the same panel, click Download .mcpb. Your browser opens the Forgejo releases page.
Download tiletopia.mcpb from the latest release (sits next to tiletopia_<version>_x64-setup.exe).

(If you're building from source, run pnpm run build:mcpb from the repo root — the bundle lands at dist-mcpb/tiletopia.mcpb.)

3. Install the bundle in Claude Desktop

Open Claude Desktop → Settings → Extensions
Drag and drop the tiletopia.mcpb file onto the extensions panel
Claude Desktop will show "tiletopia" with an Install / Enable button
Restart Claude Desktop (or the extension launcher will spawn on next chat)

4. Allow per-pane visibility

By default, no panes are visible to MCP — even with the server running. Pane visibility is opt-in.

In any tiletopia pane's toolbar, click the 🤖 chip. It flips green when enabled.
Repeat for any pane you want Claude to see / interact with.

5. Test

In a new Claude Desktop chat:

"list my tiletopia panes"

Claude should call the tiletopia/list_panes tool (or a wrapper) and reply with your visible panes. If it says it can't reach the server, see Troubleshooting.

How the bundle works (and why it's zero-config)

The .mcpb ships a tiny Node wrapper as its entry point. At launch the wrapper:

Reads %APPDATA%\com.megaproxy.tiletopia\mcp.json to get the live port and bearer token.
Execs npx -y mcp-remote http://127.0.0.1:<port>/mcp --allow-http --header "Authorization: Bearer <token>".
Proxies all subsequent JSON-RPC traffic through that shim.

Implications:

No secrets in the bundle. Same .mcpb works for every tiletopia install — the token is read on the user's own machine at runtime.
Token rotation is transparent. If you click Regenerate in the panel, the next Claude Desktop launch picks up the new token automatically. No re-paste.
Server must be running when Claude wants to call it. The wrapper doesn't start tiletopia; the panel does.

Why a wrapper / `mcp-remote` shim at all

Claude Desktop's HTTP-MCP client doesn't currently honor static bearer auth (anthropics/claude-code#17152, #46879) — it tries OAuth discovery and gives up if the server doesn't speak the dance. The mcp-remote package is an stdio MCP server that internally proxies to an HTTP endpoint with whatever auth headers you specify, sidestepping Claude Desktop's HTTP-MCP path entirely. Once Anthropic ships proper bearer support, the wrapper can be retired in favor of a direct config.

What Claude can do once installed

The full surface is documented in the MCP Policy Guide. High-level:

Read: scrollback (read_pane), wait for a pane to go quiet (wait_for_idle)
Drive: send keystrokes (write_pane), spawn new local or SSH panes, close / swap / promote panes, reshape layouts, rename panes
Manage SSH: add or remove saved hosts (gated by an extra Policy-tab switch)

Every write tool is matched against your policy — by default everything pops a confirm modal you must approve. Add rules to skip prompts you trust; deny outright the ones you don't.