Localtonet MCP 서버
이 페이지의 내용 섹션 9개
Localtonet MCP 서버를 사용하면 Claude나 Cursor처럼 Model Context Protocol을 지원하는 AI 어시스턴트가 자연어로 내 계정을 관리할 수 있습니다. 터널을 조회하고, 만들고, 시작하고, 중지하고, 설정할 수 있으며 AuthToken, 토큰 그룹, 서버, SSO 제공자도 관리할 수 있습니다.
MCP 서버란 무엇이며 무엇이 아닌가 #
- 이 페이지의 MCP 서버는 Localtonet이
https://localtonet.com/mcp에서 운영합니다. 이 서버의 도구는 REST API와 마찬가지로 내 Localtonet 계정에 대해 동작합니다. - MCP 게이트웨이는 터널 유형입니다. 내 기기에서 실행되는 MCP 서버에 공개 주소를 부여합니다. 내 도구를 게시할 때 사용하며, Localtonet을 관리하는 용도가 아닙니다.
연결 정보 #
| 설정 | 값 |
|---|---|
| 엔드포인트 | https://localtonet.com/mcp |
| 전송 방식 | Streamable HTTP |
| 인증 | API 키를 Bearer 토큰으로 사용합니다. Authorization: Bearer <YOUR_API_KEY> |
| 서버 정보 | localtonet.com/mcp-info(JSON)와 https://localtonet.com/.well-known/mcp-server-card의 서버 카드 |
시작하기 전에 #
- Streamable HTTP로 원격 서버에 연결하고 사용자 지정
Authorization헤더를 보낼 수 있는 MCP 클라이언트가 필요합니다. - API 키가 필요합니다. 대시보드를 열고 API 키 카드에서 복사를 사용하세요. 계정 및 보안을 참고하세요.
- 터널 작업의 경우: 어시스턴트가 터널을 만들 AuthToken을 갖도록 Localtonet 클라이언트가 연결된 기기가 필요합니다.
MCP 클라이언트 연결하기 #
-
클라이언트에 서버 추가하기 #
대부분의 MCP 클라이언트는 원격 서버를 URL과 헤더로 받습니다. 일반적인 형태는 다음과 같습니다.
MCP 클라이언트 설정{ "mcpServers": { "localtonet": { "type": "http", "url": "https://localtonet.com/mcp", "headers": { "Authorization": "Bearer <YOUR_API_KEY>" } } } }파일 이름과 정확한 키 이름은 클라이언트마다 다릅니다. 원격 MCP 서버를 어디에서 설정하는지는 사용 중인 클라이언트의 문서를 확인하고, 위의 URL과 헤더를 사용하세요.
-
연결 확인하기 #
클라이언트를 다시 로드하세요. 도구 목록에 Localtonet 도구가 나타나야 합니다. 먼저 무해한 요청부터 해 보세요. 예를 들면 다음과 같습니다.
프롬프트List my Localtonet tunnels and tell me which ones are running. -
터널 만들기 #
원하는 내용을 설명하세요. 예를 들면 다음과 같습니다.
프롬프트Create an HTTP tunnel with a random subdomain for port 3000 on my device "laptop", then start it and give me the URL.어시스턴트는 서버가 정해 둔 워크플로를 따릅니다. 기기의 AuthToken을 조회하고, 서버를 고르고, 맞는 생성 도구를 호출하고, 터널을 시작합니다. 새로 만든 터널은 실행 중이 아니기 때문입니다.
도구 #
아래의 도구 이름은 클라이언트에 표시되는 이름입니다. 실패한 도구는 Error:로 시작하는 메시지를 반환합니다.
터널 #
| 용도 | 도구 |
|---|---|
| 조회 | GetTunnels, GetTunnel, GetTunnelRequestLogs |
| 생성 | CreateHttpRandomSubDomain, CreateHttpCustomSubDomain, CreateHttpCustomDomain, CreateTcpUdpTunnel, CreateProxyTunnel, CreateProxyTunnelWithDetail, CreateSharedProxyTunnel |
| 실행 | StartTunnel, StopTunnel, DeleteTunnel |
| 변경 | UpdateTunnelTitle, UpdateTunnelLocalIp, UpdateTunnelLocalPort, ToggleTunnelPortReserved, ToggleTunnelLegacyConnect, ChangeProxyProtocolType |
| 일괄 작업 | BulkCreateHttpRandomSubDomain, BulkCreateHttpCustomSubDomain, BulkCreateHttpCustomDomain, BulkCreateTcpUdpTunnel, BulkCreateProxyTunnel, BulkCreateProxyTunnelWithDetail, BulkCreateSharedProxyTunnel, BulkStartTunnels, BulkStopTunnels, BulkDeleteTunnels, BulkChangeProxyProtocolType |
터널 구성 #
| 설정 | 도구 |
|---|---|
| IP 제한 | GetIpRestrictions, AddIpRestriction, SetIpRestrictionMode, DeleteIpRestriction, DeleteAllIpRestrictions |
| 접근 제어 | GetAccessControls, AddAccessControl, SetAccessControlMode, DeleteAccessControl, DeleteAllAccessControls |
| 헤더와 인증 | GetTunnelHeaders, SetTunnelHeaders, GetTunnelAuthentication, SetTunnelAuthentication |
| 만료와 제한 | GetTunnelExpiration, SetTunnelExpiration, GetTunnelRateLimit, SetTunnelRateLimit, GetTunnelBandwidthLimit, SetTunnelBandwidthLimit, GetTunnelBandwidthUsage, ResetTunnelBandwidthUsage |
| 서버와 포트 | GetTunnelServerPort, SetTunnelServerPort, GetTunnelServer, SetTunnelServer |
| 인수와 메모 | GetTunnelArguments, SetTunnelArguments, GetTunnelNote, SetTunnelNote |
| 로테이팅 프록시 클라이언트와 토큰 그룹 | GetSharedProxyClients, AddSharedProxyClient, UpdateSharedProxyClient, DeleteSharedProxyClient, GetTunnelTokenGroups, SetTunnelTokenGroups |
| 고급 설정 | GetAdvancedTunnelSettings, GetTunnelIpv4Only, SetTunnelIpv4Only, GetTunnelWifiSplit, SetTunnelWifiSplit, SetTunnelSslStream, GetTunnelProxyProtocol, SetTunnelProxyProtocol, GetTunnelPassThrough, SetTunnelPassThrough, GetTunnelHttpsOnly, SetTunnelHttpsOnly, GetTunnelHttp3, SetTunnelHttp3, GetTunnelFilePath, SetTunnelFilePath, GetTunnelHostHeader, SetTunnelHostHeader, GetTunnelPathRewrite, SetTunnelPathRewrite, GetTunnelUpstreamProxy, SetTunnelUpstreamProxy, GetTunnelVless, SetTunnelVless |
각 설정의 기능은 설정 참조에 설명되어 있습니다.
AuthToken과 토큰 그룹 #
| 용도 | 도구 |
|---|---|
| AuthToken | GetAuthTokens, GetAllAuthTokens, GetAuthToken, CreateAuthToken, DeleteAuthToken, GetTunnelsByAuthToken, GetIpHistoryByAuthToken, GetArgumentsByAuthToken, SetArgumentsForAuthToken |
| 비행기 모드와 IP 변경 | GetAirplaneModeSettings, SetAirplaneModeSettings, AddChangeIpLink, DeleteChangeIpLink, AddRestartDeviceLink, DeleteRestartDeviceLink |
| 토큰 그룹 | GetTokenGroups, GetTokenGroup, CreateTokenGroup, DeleteTokenGroup, AddAuthTokenToGroup, RemoveAuthTokenFromGroup |
서버와 SSO 제공자 #
| 용도 | 도구 |
|---|---|
| 서버 | GetAvailableServers |
| SSO 제공자 | GetSsoProviders, GetSsoProviderDefaultEndpoints, SaveSsoProvider, DeleteSsoProvider, GetSsoProvidersForTunnel, SetSsoProvidersForTunnel |
프록시 터널의 VPN 액세스 #
GetVpnAccessDevices, CreateVpnAccessDevice, GetVpnAccessDeviceConfig, GetVpnAccessDeviceCredentials, RegenerateVpnAccessDevice, DeleteVpnAccessDevice. 이 도구들은 프록시 터널의 WireGuard 및 OpenVPN 기기를 관리합니다. 기기마다 고유한 구성이 있으며, 기기의 전체 트래픽이 프록시를 통해 나갑니다.
기기 #
| 도구 | 기능 |
|---|---|
ListDevices | 내 기기에서 계정과 페어링된 컴퓨터를 나열하며, 각 컴퓨터의 온라인 여부와 CPU, 메모리, 디스크 사용량을 함께 보여 줍니다. |
GetDeviceMetrics | 기기 한 대의 최신 CPU, 메모리, 디스크 사용량과 가동 시간 수치를 반환합니다. |
RunDeviceCommand | 기기에서 셸 명령 하나를 실행하고 출력과 종료 코드를 반환합니다. 지정한 시간 제한(1~120초, 기본 30초)까지 기다립니다. |
RunDeviceCommand에는 API 키 외에 기기 액세스 키가 필요합니다. 이 키는 ltd_로 시작하며 내 기기에서 해당 기기용으로 만듭니다. 기기 터미널을 참고하세요. 실행 내역은 기기의 연결 기록에 시간과 IP 주소와 함께 표시되며, 명령 자체는 저장되지 않습니다.
제한 #
- MCP 서버에 대한 요청은 내 API 키의 API 요청과 합쳐서 속도 제한을 받습니다.
429응답은 잠시 기다린 후 다시 시도하라는 뜻입니다. - 일괄 작업 도구는 최대 100개 항목의 목록을 받습니다.
안전 #
어시스턴트는 내 API 키로 동작합니다. 어시스턴트의 도구는 Localtonet 쪽 확인 단계 없이 터널을 만들고, 중지하고, 삭제할 수 있으며, AuthToken과 토큰 그룹을 삭제하고 접근 규칙을 변경할 수 있습니다.
- MCP 클라이언트에서 도구 호출 확인을 켜세요. 최소한
Delete,BulkDelete,Stop,Set으로 시작하는 도구에는 켜 두세요. RunDeviceCommand용 기기 액세스 키는 해당 컴퓨터의 터미널을 맡겨도 좋은 어시스턴트에게만 주세요. 명령은 기기의 기본 셸에서 실행됩니다.- 클라이언트 설정 파일은 비밀로 취급하세요. 이 파일에는 API 키가 들어 있습니다. 저장소에 커밋하지 마세요.
- 키가 유출되었을 수 있다면 대시보드의 API 키 카드에서 변경을 선택하세요. 새 키가 만들어지고 이전 키는 무효화됩니다. 그런 다음 MCP 클라이언트를 업데이트하세요.
- 팀 대시보드에서 복사한 API 키를 사용하면 어시스턴트는 해당 팀의 내 AuthToken과 터널만 나열합니다. 팀 관리를 참고하세요.
문제 해결 #
클라이언트가 401 또는 "API key is required. Provide Authorization: Bearer <apikey>"를 보고합니다
요청에 유효한 Authorization 헤더가 없습니다. 클라이언트가 이 서버로 사용자 지정 헤더를 보내는지, 값이 Bearer, 공백, 키 순서인지, 키를 복사한 뒤 대시보드에서 키가 변경되지 않았는지 확인하세요.
어시스턴트가 도구가 "Error: …"를 반환했다고 알려 줍니다
이는 연결 문제가 아니라 Localtonet의 응답입니다. Error: 뒤의 텍스트에 무엇이 거부되었는지가 나옵니다. 예를 들어 AuthToken이 없거나 플랜 한도에 걸린 경우입니다. 어시스턴트가 재시도하게 두지 말고 그 원인을 해결하세요.
터널이 만들어졌지만 응답하지 않습니다
어시스턴트에게 터널을 시작하라고 요청하세요. 새 터널은 StartTunnel이 호출될 때까지 중지된 상태이며, 기기의 Localtonet 클라이언트가 연결되어 있어야 합니다.
클라이언트에 도구가 보이지 않습니다
일부 클라이언트는 도구 수를 제한하거나 하나씩 활성화하도록 요구합니다. 클라이언트 설정에서 필요한 Localtonet 도구를 활성화하세요.