Use Tealhand from your AI app

Your AI app on one computer (Claude Desktop, LM Studio, Open WebUI, Cursor, or any app that speaks MCP) can ask Tealhand about your other computers: how busy they are, what they share, and what is in a text file. It can copy a file to this computer. It can never change, delete, upload, run anything or shut down a computer through Tealhand.

It is off until you turn it on.

What the AI app gets

Tealhand gives the AI app six tools. All of them read; only download_file writes, and only on this computer.

Tool	What it does
list_devices	Your other computers: id, name, online or not, when each was last seen, and the operating system when known. This computer is not in the list
device_status	CPU, GPU, memory, battery, uptime and the busiest programs of one computer
list_folders	The folders a computer shares with Tealhand. Only these can be read
list_files	One level of a shared folder: names, kinds, sizes and modified times, in pages of up to 200
read_text_file	A UTF-8 text file, at most 256 KiB per call, with an offset to read further. Binary files are refused
download_file	Copies a file into the folder for AI downloads on this computer. Never replaces a file: a taken name gets “ (1)”

Each computer still decides for itself: only its shared folders can be read, and with its remote control off they can’t be read at all (its status still can).

Turn it on

In the Tealhand app on the computer where your AI app runs: Settings, AI apps, turn on Let AI apps on this computer read your other devices and confirm with Windows Hello.

On a computer without the app, stop Tealhand Host, then:

tealhand-host mcp on
tealhand-host run

A terminal at the computer asks for no Windows Hello: it is the computer itself.

Add Tealhand to the AI app

While the switch is on, Settings, AI apps shows a button for each AI app Tealhand finds on this computer: Add to Claude Desktop, Add to LM Studio and Add to Cursor. Click it, then restart that app. The button then says “Added to Claude Desktop”.

Tealhand adds one entry named tealhand to that app’s MCP config and keeps everything else in the file as it was. The first time it changes a file, it keeps a copy next to it, ending in .tealhand-backup. When you turn AI apps off, Tealhand takes its entry out of every config it added it to.

In a terminal, the same works while Tealhand runs:

tealhand-host mcp add claude      # or lmstudio, or cursor
tealhand-host mcp remove claude

App	The config Tealhand changes
Claude Desktop	claude_desktop_config.json in its folder (%APPDATA%\Claude on Windows, ~/.config/Claude on Linux)
LM Studio	~/.lmstudio/mcp.json
Cursor	~/.cursor/mcp.json (its global config)

Any other AI app

Click Copy setup (or run tealhand-host mcp setup) and paste it into the AI app’s MCP settings. It looks like this (the path is where tealhand-host is on your computer):

{
  "mcpServers": {
    "tealhand": {
      "command": "C:\\Program Files\\Tealhand\\tealhand-host.exe",
      "args": ["mcp"]
    }
  }
}

Restart the AI app. Ask it “What are my other computers doing?” or “Read notes/todo.md on Cloud PC”.

The setup holds no password or token. tealhand-host mcp gets what it needs from your user account’s credential store (Windows Credential Manager, the Linux secret service). AI apps that only take a web address and a token are not supported, because the token would have to sit in their settings.

Where copies go

download_file saves into Downloads/Tealhand in your home folder. Settings, AI apps, Change picks another folder (tealhand-host mcp folder <dir>). The largest file it copies is 1 GB by default (tealhand-host mcp limit <MB>, up to 65536).

What you see

• Activity on this computer lists every call as “AI app via MCP”, with the tool, the computer, and a file or folder name, or why it was refused. Never a path or file content.
• Your phone gets no notice for AI reads. Notices on the phone are for changes, and an AI app makes none.

Safety

• Read only, enforced by Tealhand. The allow-list is in Tealhand’s code, not in what the tools tell the model: a request to delete, upload, run or shut down is refused before it leaves this computer, and checked again before it is signed.
• The same gates on every computer. The calls go through this computer’s own connection to your other computers, so each one applies its remote control switch and its shared folders.
• Nothing new on the network. The endpoint listens on 127.0.0.1 only and needs a token kept in your user account’s credential store, never in a plain file. Other computers, and web pages in your browser, can’t use it.
• Files are data. A text file can say anything, including “delete everything”. Through Tealhand the model can only read, so such text can’t change your computers.
• Off at once. Turning the switch off closes the endpoint, deletes its token and takes Tealhand out of the AI apps’ configs.

Problems

The AI app or Tealhand says	Fix
“AI apps are off on this computer”	Turn on the switch in Settings, AI apps, or run tealhand-host mcp on
“Tealhand is not running on this computer”	Open the Tealhand app, or run tealhand-host run
“Tealhand refused the saved token”	Restart the Tealhand app or tealhand-host run
“the AI apps token can’t be read”	Unlock your credential store (Linux: the keyring), or turn AI apps off and on again
“Remote control is off on …”	Turn on remote control in Tealhand on that computer
“Claude Desktop isn’t installed for this user”	Install it, or use Copy setup
“… isn’t valid JSON, so Tealhand left it alone”	Fix that config file, or paste the setup by hand
“AI apps start tealhand-host, and it isn’t next to Tealhand or on PATH”	Put tealhand-host.exe next to Tealhand.exe or in a folder on PATH, then Check again