Localtonet MCP server

The Localtonet MCP server lets an AI assistant that supports the Model Context Protocol, such as Claude or Cursor, manage your account in natural language: list, create, start, stop and configure tunnels, and manage AuthTokens, token groups, servers and SSO providers.

What it is, and what it is not #

• The MCP server on this page is run by Localtonet at https://localtonet.com/mcp. Its tools act on your Localtonet account, the same way the REST API does.
• The MCP Gateway is a tunnel type. It gives an MCP server that runs on your own device a public address. Use it to publish your own tools, not to manage Localtonet.

Connection details #

Before you start #

• An MCP client that can connect to a remote server over Streamable HTTP and send a custom Authorization header.
• Your API key. Open the Dashboard and use Copy in the API Key card. See Account and security.
• For tunnel work: a device with the Localtonet client connected, so the assistant has an AuthToken to create tunnels on.

Connect your MCP client #

1. Add the server to the client #

   Most MCP clients take a remote server as a URL plus headers. The usual shape is:

   MCP client configuration

   {
     "mcpServers": {
       "localtonet": {
         "type": "http",
         "url": "https://localtonet.com/mcp",
         "headers": {
           "Authorization": "Bearer <YOUR_API_KEY>"
         }
       }
     }
   }

   The file name and the exact key names differ between clients. Check the documentation of your client for where remote MCP servers are configured, and use the URL and the header from above.

2. Check the connection #

   Reload the client. The Localtonet tools should appear in its tool list. Ask something harmless first, for example:

   Prompt

   List my Localtonet tunnels and tell me which ones are running.

3. Create a tunnel #

   Describe what you want. For example:

   Prompt

   Create an HTTP tunnel with a random subdomain for port 3000 on my device "laptop", then start it and give me the URL.

   The assistant follows the workflow the server prescribes: it looks up the AuthToken of the device, picks a server, calls the matching create tool, and starts the tunnel, because a newly created tunnel is not running.

Tools #

The tool names below are the names your client shows. A tool that fails returns a message that starts with Error:.

Tunnels #

Tunnel configuration #

What the settings do is described in the Settings reference.

AuthTokens and token groups #

Servers and SSO providers #

VPN access on proxy tunnels #

GetVpnAccessDevices, CreateVpnAccessDevice, GetVpnAccessDeviceConfig, GetVpnAccessDeviceCredentials, RegenerateVpnAccessDevice, DeleteVpnAccessDevice. These tools manage WireGuard and OpenVPN devices on a proxy tunnel. Each device gets its own configuration, and its whole traffic leaves through the proxy.

Devices #

RunDeviceCommand needs more than the API key: it requires a device access key (it starts with ltd_) that you create for that device under My Devices. See Device Terminal.

Limits #

• Requests to the MCP server are rate limited, together with the API requests of your API key. A 429 answer means: wait, then try again.
• Bulk tools accept a list of up to 100 items.

Safety #

• Turn on confirmation for tool calls in your MCP client, at least for the tools that start with Delete, BulkDelete, Stop and Set.
• Give the device access key for RunDeviceCommand only to an assistant you would also give a terminal on that computer. A command is run by the default shell of the device.
• Treat the client configuration file as a secret: it contains your API key. Do not commit it to a repository.
• If the key may have leaked, select Change in the API Key card of the dashboard. This creates a new key and invalidates the old one; then update your MCP client.
• With an API key copied in a team dashboard, the assistant lists only your AuthTokens and tunnels in that team. See Team Management.

Troubleshooting #

The client reports 401, or "API key is required. Provide Authorization: Bearer <apikey>"

The request has no valid Authorization header. Check that the client sends custom headers for this server, that the value is Bearer, a space, then the key, and that the key was not changed in the dashboard since you copied it.

The assistant says a tool returned "Error: …"

That is the answer of Localtonet, not a connection problem. The text after Error: says what was refused, for example a missing AuthToken or a plan limit. Fix that cause instead of letting the assistant retry.

The tunnel was created but does not answer

Ask the assistant to start it. A new tunnel is stopped until StartTunnel is called, and the Localtonet client of the device must be connected.

Tools are missing in my client

Some clients limit the number of tools or ask you to enable them one by one. Enable the Localtonet tools you need in the client settings.

Related pages #