LocalCan

MCP 서버

LocalCan의 Model Context Protocol 서버를 실행하고 MCP 호스트에 연결하세요. 도구와 스위치에 대한 전체 참조가 포함되어 있습니다.

localcan mcp는 stdio를 통해 Model Context Protocol 서버를 실행합니다. MCP 호스트(Claude Code, Codex, Cursor, Claude Desktop 등)가 이를 실행하고 LocalCan의 도구를 호출하여 캡처된 트래픽을 읽고, Public URL(터널)을 관리하며, Snapshot을 게시합니다. 도구가 데이터를 반환하려면 LocalCan이 실행 중이어야 하므로, 데스크톱 앱을 열거나 먼저 localcan start -d를 실행하세요.

도구

서버는 26개의 도구를 제공합니다. 읽기는 기본적으로 작동합니다. 변경을 수행하는 16개의 도구는 쓰기 권한이 필요하며, 기본적으로 꺼져 있습니다(아래 스위치 참조). Public URL을 생성하거나 추가하려면 활성 라이선스가 필요합니다. Snapshot 게시와 URL 비밀번호 보호는 구독 플랜이 필요하므로, 영구 라이선스는 Public URL을 열 수 있음에도 불구하고 거부됩니다. 라이선스가 없으면 제한된 도구는 명확한 활성화 메시지를 반환하지만, 기존 URL의 일시 중지, 재개, 제거는 여전히 작동합니다.

트래픽:

도구	기능	매개변수
get_status	캡처가 켜져 있는지와 버퍼링된 트래픽 양을 보고합니다.	없음
enable_capture	캡처를 켭니다. 캡처는 기본적으로 꺼져 있으며 데몬이 재시작되면 초기화됩니다.	없음
list_traffic	최근 교환을 최신순으로 나열합니다.	last (기본값 20), host 부분 문자열, project ID, method, status (정확한 코드 또는 5xx 같은 클래스)
get_exchange	ID로 교환 하나를 반환합니다.	id 필수 (전체 ID 또는 고유한 접두사), format markdown, curl, http, har, json 중 하나 (기본값 markdown), include_response (기본값 true)

교환은 LocalCan이 백엔드로 전달한 요청이며, 클라이언트의 원래 요청을 바이트 단위로 복사한 것이 아닙니다. 데이터 모델은 트래픽을 참조하세요.

Public URL:

도구	기능	매개변수
list_services	LocalCan이 제공하는 서비스를 나열하며, 각 서비스에는 <project>/<service> 핸들, 로컬 대상, 엔드포인트 수가 포함됩니다.	없음
list_public_urls	일시 중지된 URL을 포함한 Public URL을 나열하며, 각각의 상태(active, paused, error, starting, inactive)와 제공 내용(live, snapshot, none)을 표시합니다. 모든 행에는 access도 포함됩니다: none, password, link 또는 팀 정책 이름. Snapshot을 제공하는 대기 중인 URL은 상태가 paused이지만 serving snapshot으로 읽히므로, "링크가 살아 있나요?"라는 질문에는 상태가 아닌 serving 기준으로 답하세요.	없음
get_public_url_status	하나의 Public URL 상태, 제공 내용(live, snapshot, none), access 보호를 목록과 동일한 용어로 보고하며, 로컬 대상과 요청 헤더 규칙도 포함합니다.	url 필수
create_public_url	새 프로젝트의 로컬 포트에 Public URL을 생성하고 할당된 주소를 반환합니다(예: my-app-12.localcan.dev). 몇 초가 걸립니다. 터널이 거부되거나(예: 플랜의 Public URL 제한) 시간 초과되면 시도가 롤백되고 아무것도 남지 않습니다. 머신이 오프라인이 된 후에도 계속 접근 가능한 링크를 원하면 add_snapshot로 Snapshot을 추가하세요. 가상 호스트로 제공되는 앱의 경우 host와 headers의 Host 규칙을 전달하세요(아래 참조).	port 필수, name 선택 사항(주소 형태 지정), protocol http 또는 tcp (기본값 http), host 선택 사항(기본값 localhost), headers 선택 사항(요청 헤더 규칙, 각 {name, value, mode?, enabled?})
add_public_url	이미 구성된 서비스에 Public URL을 추가합니다. 프로토콜은 서비스의 대상을 따르므로 tcp:// 대상은 TCP 터널을 얻습니다. 생성과 동일한 실패 시 롤백이 적용됩니다.	service 핸들 필수
pause_public_url	주소를 유지하면서 Public URL을 오프라인으로 전환하여 나중에 재개할 수 있게 합니다. 생성된 *.localcan.dev 주소는 일시 중지된 동안 7일간 예약되며, 사용자 정의 도메인은 만료되지 않습니다.	url 필수
resume_public_url	일시 중지된 Public URL을 동일한 주소로 다시 온라인 상태로 전환합니다.	url 필수
remove_public_url	Public URL을 영구적으로 제거합니다. 생성된 주소는 해제되고, 사용자 정의 도메인은 사용자 소유로 유지되어 다시 추가할 수 있습니다. 서비스의 마지막 엔드포인트를 제거하면 비워진 서비스와 프로젝트도 제거됩니다. 주소를 유지하면서 Snapshot 제공을 중지하려면 remove_snapshot를 사용하세요. 파괴적 작업으로 표시되어 호스트는 일반적으로 확인을 요청합니다.	url 필수
set_public_url_headers	Public URL의 요청 헤더 규칙을 교체합니다. LocalCan이 앱에 전달하기 전에 설정하는 헤더입니다. 전체 목록을 전달하고, 빈 목록은 규칙을 지웁니다. get_public_url_status는 동일한 형태로 규칙을 보고하므로(mode set, append, remove 및 enabled), 거기서 읽은 목록을 편집하고 다시 쓸 수 있습니다.	url 및 headers 필수

가상 호스트로 제공되는 앱(myapp.test의 Laravel Herd 또는 Valet 사이트, nginx server_name)은 자체 호스트 이름을 볼 수 있어야 하며, LocalCan은 기본적으로 공개 호스트 이름을 전달합니다. host와 Host 규칙 headers: [{"name": "Host", "value": "{{target_host}}"}]를 전달하면 앱이 올바른 사이트를 제공합니다. 값 템플릿은 헤더의 것과 동일합니다.

스냅샷(스냅샷 참조):

도구	기능	매개변수
publish_snapshot	폴더를 새 Public URL의 Snapshot으로 게시하여 머신이 오프라인이 된 후에도 계속 접근 가능하게 합니다. 가능하면 빌드된 정적 출력을 가리키거나, LocalCan이 빌드할 프로젝트 루트를 가리키세요(의존성은 이미 설치되어 있어야 함). 새 주소를 반환합니다. 항상 새 URL을 생성하므로 기존 미리보기를 새로 고치려면 update_snapshot를 사용하세요.	path 필수 (절대 경로), name 선택 사항(주소 형태 지정)
add_snapshot	이미 보유한 Public URL에 Snapshot을 추가하여 기존 링크가 오프라인에서도 계속 제공되게 합니다. URL에 이미 Snapshot이 있으면 update_snapshot를 가리킵니다.	url 및 path 필수
update_snapshot	Public URL의 Snapshot을 다시 게시합니다. 동일한 소스에서 다시 빌드하려면 path를 생략하고, 다른 폴더를 가리키려면 전달하세요. URL에 Snapshot이 없으면 add_snapshot를 가리킵니다.	url 필수, path 선택 사항
remove_snapshot	Public URL에서 Snapshot을 제거합니다. URL은 예약된 상태로 유지되며 터널이 올라와 있는 동안 라이브 제공을 계속합니다. 파괴적 작업으로 표시됩니다.	url 필수
get_snapshot_status	Public URL의 Snapshot을 보고합니다: 소스 폴더, 게시 시점, 소스가 이후 변경되었는지(stale), URL이 현재 라이브 또는 스냅샷을 제공하는지. 또한 리뷰 댓글(상태 및 개수)과, 댓글이 켜진 후의 Snapshot 버전 번호도 포함합니다.	url 필수

접근 제어(접근 제어 참조):

도구	기능	매개변수
set_password	Public URL을 비밀번호로 보호하여 비밀번호를 가진 사람만 열 수 있게 합니다. LocalCan 서버에서 적용되므로 해당 URL의 Snapshot도 보호됩니다. 비밀번호를 전달하지 않으면 강력한 비밀번호를 생성하고 공유할 수 있도록 반환합니다. 구독 플랜이 필요합니다.	url 필수, password 선택 사항(생략 시 생성)
clear_access	비밀번호 보호를 제거하여 URL을 다시 공개합니다. URL이나 Snapshot은 제거하지 않습니다. 파괴적 작업으로 표시되어 호스트는 일반적으로 확인을 요청합니다.	url 필수
get_access_status	Public URL의 보호 상태를 보고하고, 비밀번호로 보호된 경우 현재 비밀번호를 반환합니다. 비밀번호는 list_public_urls에서는 절대 반환되지 않으며 여기서만 반환됩니다.	url 필수

댓글(리뷰어가 Snapshot에 남기는 리뷰 댓글, 댓글 참조):

도구	기능	매개변수
list_comments	Public URL의 Snapshot에 대한 댓글 스레드를 답글과 함께 나열합니다. 각 스레드에는 페이지 경로, 앵커(CSS 선택자와 해당 요소 내 핀 위치), 리뷰어의 뷰포트와 브라우저, 댓글이 남겨진 Snapshot 버전이 포함됩니다. 읽음 표시는 절대 하지 않습니다.	url 필수, status open, resolved 또는 all (기본값 open), page 경로, version 번호
reply_comment	계정 이름으로 스레드에 답글을 게시합니다. 팀의 답글 알림이 꺼져 있거나 구독을 취소하지 않은 경우 스레드의 리뷰어가 이메일로 받습니다. 답글만 가능하며, 새 스레드는 페이지에 고정됩니다.	url, comment_id, body 필수
resolve_comment	스레드를 답글 포함하여 해결됨으로 표시합니다.	url 및 comment_id 필수
reopen_comment	해결된 스레드를 다시 엽니다.	url 및 comment_id 필수
set_comments	Snapshot의 댓글을 전환합니다: on, paused(기존 스레드는 읽을 수 있지만 새 스레드는 없음) 또는 off. 보호된 URL과 구독 플랜이 필요합니다.	url 및 state 필수

피드백 루프

도구는 에이전트가 스스로 실행할 수 있는 하나의 루프로 연결됩니다: list_comments로 열린 스레드를 읽고, 소스를 편집하고, update_snapshot로 새 버전을 게시한 다음, 스레드별로 reply_comment 및 resolve_comment를 실행합니다. 댓글은 새 버전으로 이어지므로 리뷰어는 동일한 핀에서 답글을 볼 수 있습니다. 서버는 에이전트에게 이를 직접 알려줍니다. 호스트가 에이전트 프롬프트에 추가하는 MCP 지침은 루프, 리뷰 라운드 설정(publish_snapshot, set_password, set_comments) 및 가상 호스트 레시피를 설명합니다. 에이전트가 할 수 없는 두 가지: 스레드 시작(리뷰어가 페이지에 고정) 및 스레드 읽음 표시(읽지 않음은 앱의 개인 받은 편지함 상태).

에이전트 연결

연결 방법은 에이전트가 실행되는 방식에 따라 다릅니다. 터미널 에이전트(Claude Code, Codex)는 셸 PATH를 상속하므로 localcan 명령만으로 충분합니다. GUI 앱(Cursor, Claude Desktop, VS Code 등)은 셸 PATH를 로드하지 않으므로 바이너리의 절대 경로가 필요합니다(예: /Users/you/.localcan/bin/localcan). 데스크톱 앱의 설정에서 올바른 경로가 채워진 준비된 구성을 복사할 수 있으며, Windows에서도 안정적인 방법입니다.

Claude Code

claude mcp add --scope user localcan -- localcan mcp

--scope user 플래그는 모든 프로젝트에 서버를 등록합니다. 현재 프로젝트에만 등록하려면 제거하세요.

Codex

codex mcp add localcan -- localcan mcp

이렇게 하면 서버가 ~/.codex/config.toml에 기록됩니다. Codex 데스크톱 앱 또는 IDE 확장의 경우 localcan 대신 절대 경로를 전달하세요.

Cursor, Claude Desktop 및 Windsurf

이들은 동일한 mcpServers 형식을 공유합니다:

{
  "mcpServers": {
    "localcan": {
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

올바른 파일에 추가한 후 다시 로드하세요:

• Cursor: ~/.cursor/mcp.json, 그런 다음 설정에서 서버를 활성화하세요.
• Claude Desktop: claude_desktop_config.json (설정, 개발자, 구성 편집), 그런 다음 종료하고 다시 실행하세요.
• Windsurf: ~/.codeium/windsurf/mcp_config.json, 그런 다음 MCP 패널을 새로 고치세요.

VS Code

VS Code(Copilot 에이전트 모드)는 명시적 유형의 servers 키를 사용합니다. 작업 공간의 .vscode/mcp.json에 다음을 추가하세요:

{
  "servers": {
    "localcan": {
      "type": "stdio",
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

동일한 서버 객체로 code --add-mcp를 실행할 수도 있습니다.

Zed

Zed는 settings.json에서 context_servers를 사용합니다:

{
  "context_servers": {
    "localcan": {
      "source": "custom",
      "command": "/Users/you/.localcan/bin/localcan",
      "args": ["mcp"]
    }
  }
}

에이전트 패널 설정에서 추가할 수도 있습니다.

에이전트 접근, 편집(redaction) 및 쓰기 권한

세 가지 모두 데스크톱 앱의 설정("AI Agents (MCP)" 섹션)에서 제어하거나 터미널에서 제어할 수 있습니다: 에이전트 접근은 localcan mcp enable / disable, 편집은 localcan mcp redact <on|off>, 쓰기 권한은 localcan mcp access <read_only|read_write>, 현재 상태 확인은 localcan mcp status를 사용하세요.

• 에이전트 접근은 기본적으로 켜져 있습니다. 끄면 에이전트가 LocalCan을 전혀 사용할 수 없게 됩니다. 서버는 계속 시작되지만, 다시 켤 때까지 모든 도구가 명확한 "접근이 비활성화되었습니다" 메시지를 반환합니다.
• 에이전트에 대한 편집(Redaction)은 기본적으로 켜져 있습니다. 민감한 헤더(Authorization, 쿠키, API 키)는 도구 응답에서 제거됩니다. URL과 본문은 편집되지 않습니다. 끄면 자신의 에이전트가 원시 값을 받을 수 있습니다.
• 쓰기 접근은 기본적으로 꺼져 있습니다. 읽기는 접근 없이도 작동하지만, 쓰기 도구는 앱에서("에이전트가 Public URL을 만들고 변경하도록 허용") 또는 localcan mcp access read_write로 켤 때까지 명확한 읽기 전용 메시지를 반환합니다. 에이전트 접근을 켜도 쓰기 접근이 부여되지는 않습니다. 이들은 별도의 스위치입니다. 모든 쓰기 호출은 서버의 진단 출력에 기록되며, 호스트가 이를 캡처하므로 에이전트가 변경한 내용의 기록을 확인할 수 있습니다. set_password에 전달된 비밀번호는 해당 로그에서 마스킹됩니다.

도구가 거부하는 경우

• 모든 도구는 데몬 연결 메시지와 함께 오류를 반환합니다: LocalCan이 실행 중이 아닙니다. 데스크톱 앱을 열거나 localcan start -d를 실행하세요.
• list_traffic는 아무것도 반환하지 않습니다: 캡처가 꺼져 있습니다(기본적으로 꺼져 있으며 데몬이 다시 시작되면 초기화됩니다). localcan traffic enable를 실행하거나 에이전트가 enable_capture를 호출하게 하세요.
• "MCP 접근이 비활성화되었습니다": 에이전트 접근이 꺼져 있습니다. localcan mcp enable를 실행하거나 Settings 토글을 전환하세요.
• "MCP가 읽기 전용입니다": 도구가 내용을 변경하며 쓰기 접근이 꺼져 있습니다. localcan mcp access read_write를 실행하거나 Settings 토글을 켜세요.
• "public URLs require a license": Public URL을 만들고 추가하려면 활성 라이선스가 필요합니다. 앱에서 활성화하거나 localcan license activate <key>로 활성화하세요.
• "need a subscription plan": Snapshot 및 Access control은 구독 전용입니다. 영구 라이선스는 Public URL을 열 수 있지만 Snapshot을 게시하거나 비밀번호를 설정할 수는 없습니다. dashboard에서 구독한 후 다시 시도하세요.
• "already has a snapshot" 또는 "has no snapshot yet": 메시지에 이름이 지정된 도구를 사용하세요. add_snapshot는 Snapshot이 없는 URL에 Snapshot을 첨부하고, update_snapshot는 이미 있는 Snapshot을 새로 고칩니다.
• "Snapshot limit reached": 요금제에 따라 동시에 Snapshot을 제공할 수 있는 Public URL 수가 제한됩니다. 메시지에는 이미 슬롯을 사용 중인 URL이 나열되며, 새로 게시하는 대신 update_snapshot로 새로 고칠 수 있습니다.
• "Comments need a protected URL": set_comments가 Access control이 없는 URL에서 호출되었습니다. 먼저 set_password를 실행하세요.
• "Your account has no display name": 답변을 게시하려면 이름이 필요합니다. dashboard에서 설정하거나, 앱에서 소유자로 연 후 Snapshot 페이지에서 한 번 답변하세요.
• 호스트가 서버를 실패 또는 도구 없음으로 표시합니다: GUI 앱이 PATH에서 localcan를 찾을 수 없습니다. 절대 경로를 사용하세요. 가장 쉬운 방법은 Settings의 구성 복사 기능을 이용하는 것입니다.