Docs

Your connection

Use this address wherever your client asks for the remote MCP server URL.

https://mcp.tethershell.com/mcp

Tool arguments and results pass through the Tethershell backend. File writes and commands follow the permissions configured on your device.

Install a device agent

Each Linux computer you want to use with Tethershell runs the standalone agent. Install Node.js 22 or later, then clone the public agent repository:

git clone https://github.com/tethershell/tethershell-agent.git
cd tethershell-agent
npm install --omit=dev

Tethershell agent on GitHub

After installing, create your account. Once approved, sign in and use Agent setup to pair the workspace you want to expose. The agent repository README also includes systemd, updating, security and troubleshooting instructions.

ChatGPT

1. Enable Developer mode under Settings → Security and login. Availability depends on your account and workspace policy.
2. Open Plugins → Browse plugins. In the plugin browser, click the + next to the search bar to add a custom plugin (MCP), then name it Tethershell. If your interface uses Apps or Connectors instead, open its custom MCP connection form.
3. Choose Server URL, paste the MCP URL above, and select OAuth. Leave optional client ID and secret fields empty; Tethershell supports dynamic registration.
4. Create the connection, then use Sign in with Tethershell to authorize your account.
5. Start a new chat and enable Tethershell from the tools menu. Ask it to list your connected devices.

After a tool update, refresh the connection in Plugins and start a new chat.

Official ChatGPT connection guide

Codex

Run these commands on the machine where you use the Codex CLI:

codex mcp add tethershell --url 'https://mcp.tethershell.com/mcp'
codex mcp login tethershell
codex mcp list

Complete the browser sign-in with your Tethershell account. If adding the server already signed you in, the separate login step is unnecessary. Start or restart Codex, then use /mcp to check the connection.

Alternatively, add this entry to ~/.codex/config.toml and run the login command above:

[mcp_servers.tethershell]
url = "https://mcp.tethershell.com/mcp"

The Codex IDE extension shares this configuration on the same host. Its MCP servers settings also let you add a Streamable HTTP server and authenticate, then restart the extension.

Official Codex MCP guide

Claude

1. Open Customize → Connectors in Claude. On an eligible individual plan, select + → Add custom connector.
2. Enter the name Tethershell and the MCP URL above. Leave optional OAuth client credentials empty, then add the connector.
3. Select Connect and sign in with your Tethershell account.
4. In a conversation, open + → Connectors and enable Tethershell. Ask Claude to list your devices.

For Team or Enterprise, an organization owner must first add the custom web connector in Organization settings → Connectors. Each member then connects their own Tethershell account.

Use the account connector flow for Claude web and Desktop. Remote connectors reach Tethershell from Anthropic’s servers, so the MCP endpoint must be publicly reachable over HTTPS.

Official Claude custom connector guide

Claude Code

Add the remote server to your user configuration so it is available across projects:

claude mcp add --transport http --scope user tethershell 'https://mcp.tethershell.com/mcp'

Open Claude Code, enter /mcp, select Tethershell, and follow the authentication prompt. Sign in in the browser, then return to your session.

claude mcp get tethershell
claude mcp list

Adding the server saves its configuration; it still needs a successful sign-in. Complete authentication interactively before running unattended jobs under that same local user. Use /mcp to reauthenticate when needed.

Official Claude Code MCP guide

Other MCP clients, harnesses & agents

Use the client’s remote MCP settings and supply the URL above. Choose Streamable HTTP and OAuth, then complete browser sign-in. Configuration field names vary by client; there is no universal MCP configuration file.

A client with only local stdio support needs a compatible local adapter that supports both remote HTTP and OAuth. A client that only accepts an API key cannot connect using your account password or device token. Tethershell currently does not issue personal API keys.

For a custom harness, use an MCP SDK’s Streamable HTTP transport with its OAuth client support. Keep authorization separate from model prompts; pass tool results back to the model only after the MCP client has authenticated.

Check the connection

Try this first:

Use Tethershell to list my connected devices and report which are online. Do not run commands or modify files.

You should see only devices paired to your account. An empty list means no devices are paired to the account you authorized. Once a device is online, ask to list its workspace files before trying commands.