도구, 프로필, 승인을 위한 Zaru의 엔드포인트 하나

다른 언어: English, Español, Português, 日本語, Deutsch, Français, 简体中文, Italiano, हिन्दी · 한국어 가이드 전체

공개: Zaru는 100monkeys AI, Inc.가 만들고 있으므로 이 가이드는 만든 쪽의 설명으로 읽어 주세요. 이 가이드는 저희 AI 에이전트 하나가 2026년 10월 29일에 읽은 Zaru 문서(영어)(Connect Zaru to Any MCP Client, MCP Tools, Profiles, API Keys, The Vault, Calendar, Refusals and Errors)를 바탕으로 초안을 쓰고 회사가 검토했으며, 이 한국어판은 영어 원문 가이드의 번역입니다. 아래의 모든 명령, 헤더, 메시지는 그 페이지들에서 그대로 옮겼고, 인용은 영어 그대로 두고 옆에 번역을 붙였습니다. 문서가 어떻게 동작하는지 말하지 않는 부분은 지어내지 않고 말하지 않는다고 적었습니다.

메일함, 캘린더, GitHub token, Carbon Forge token을 Zaru에 두면 Claude Code는 하나의 주소로 그 모두에 닿을 수 있습니다. token은 Zaru에 남고, 키가 그중 무엇을 건드릴 수 있는지는 프로필이 정하며, 무언가를 보내거나 바꾸는 호출은 Zaru Web에서 여러분의 답을 기다립니다. 이 가이드는 zaru init부터 첫 보류된 호출까지를 따라갑니다.

1단계. 도구가 쓸 것을 연결하기

Get Zaru free로 가입하세요. 이름과 이메일만 있으면 됩니다. Vault의 Connections 페이지에서 Google 메일함, Google Calendar, IMAP과 SMTP를 쓰는 메일함, CalDAV를 쓰는 캘린더를 연결합니다. GitHub token이나 Carbon Forge MCP token은 New Credential로 저장합니다. 값에 대해 문서는 분명합니다: "No agent, operator, API key or other person is given the value." (어떤 에이전트, 운영자, API 키, 다른 사람도 그 값을 받지 않습니다.)

2단계. 프로필 만들기

키는 무엇에 닿아도 되는지 여러분이 정하기 전까지 아무것에도 닿지 않습니다. API Keys 페이지는 목록 위에 이렇게 적습니다: "A key reaches only the connections in the profile you choose for it; with no profile it reaches none." (키는 그 키에 고른 프로필의 연결에만 닿습니다. 프로필이 없으면 어디에도 닿지 않습니다.) 에디터가 가져야 할 연결과 도구로 프로필을 만드세요. 양식은 Zaru 실행마다 필요한 연결만 주기에서 단계별로 설명합니다.

3단계. API 키를 만들고 그 프로필 고르기

Settings → API Keys를 열고 New API Key를 눌러 이름을 붙이고, 범위 프리셋을 고르고, 키의 프로필을 고르고(기본값은 None), 만료를 고른 뒤 Create를 누릅니다. "The key value is shown once." (키 값은 한 번만 표시됩니다.)

4단계. Claude Code에 엔드포인트 추가하기

모든 클라이언트는 하나의 주소 https://mcp.myzaru.com/mcp/v1에 StreamableHTTP로 연결하고, 키를 Bearer token으로 씁니다. Claude Code에 대해 문서가 주는 명령은 다음과 같습니다:

claude mcp add zaru \
  --transport http \
  https://mcp.myzaru.com/mcp/v1 \
  --header "Authorization: Bearer YOUR_API_KEY"

같은 페이지에 Claude Desktop, Cursor, Windsurf, VS Code(GitHub Copilot), Gemini CLI, 그리고 StreamableHTTP를 쓰는 모든 클라이언트의 설정이 있습니다.

5단계. zaru init 입력하기

세션에서 어시스턴트에게 이렇게 말하세요:

zaru init

어시스턴트는 zaru.init 도구를 호출하고 Zaru 페르소나를 씁니다. zaru init agentic은 지정한 모드로 시작합니다. 이것은 MCP 서버의 도구입니다. Zaru CLI 가이드에 나오는 명령줄 프로그램의 zaru init과는 관계가 없고, 그쪽은 Zaru Web에 연결하지 않습니다.

6단계. 필요하면 연결마다 프로필 고르기

키의 프로필은 모든 요청에 적용됩니다. 대신 클라이언트는 예약된 키 @profile만 담은 x-zaru-contexts 헤더를 보낼 수 있습니다:

x-zaru-contexts: {"@profile":"0000daeb-ae45-4d06-9712-9d498a653b24"}

이 id는 문서의 예시입니다. 키로 연결한 경우 요청의 @profile이 그 요청에 한해 키 자체의 프로필을 대신하고, 제공되는 도구도 그 프로필의 것이 됩니다. 다른 형태는 모두 400으로 응답받습니다.

헤더를 넣는 곳은 Connect Zaru to Any MCP Client 페이지에 있습니다: "Every client above sends one header, Authorization, from its configuration. The same place takes a second header, x-zaru-contexts, which chooses for every request of that connection which of your connections its tools use." (위의 모든 클라이언트는 설정에서 Authorization 헤더 하나를 보냅니다. 같은 곳에 두 번째 헤더 x-zaru-contexts를 넣을 수 있으며, 이 헤더는 그 연결의 모든 요청에서 도구가 여러분의 어느 연결을 쓸지 고릅니다.) Claude Code에서는 두 번째 --header를 붙입니다:

claude mcp add zaru \
  --transport http \
  https://mcp.myzaru.com/mcp/v1 \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header 'x-zaru-contexts: {"@profile":"<profile id>"}'

JSON으로 설정하는 클라이언트(Claude Desktop, Windsurf, VS Code)에서는 headers 아래 두 번째 항목이 됩니다. "The profile's id is the last part of the address of its page in Zaru Web, ask.myzaru.com/vault/profiles/<profile id>." (프로필 id는 Zaru Web에 있는 그 프로필 페이지 주소의 마지막 부분입니다.) 문서가 열어 둔 것이 하나 있습니다: "Whether a given client sends a header it was configured with on every request is the client's behaviour, not documented here." (설정한 헤더를 클라이언트가 모든 요청마다 보내는지는 클라이언트의 동작이며, 여기서는 문서화되어 있지 않습니다.)

7단계. 연결을 쓰는 호출 하기

클라이언트에는 프로필의 연결 계열 도구가 나열됩니다. 메일함이면 메일 도구, 캘린더면 캘린더 도구, GitHub나 Carbon Forge면 원격 서버의 도구입니다. 메일함이나 계정을 지정하지 않은 메일 또는 캘린더 호출은 하나뿐이면 그것을, 아니면 가장 최근 것을 쓰고, 응답의 mailbox_name 또는 account_name에 그 이름이 담깁니다. 캘린더 도구에 대해 문서는 이렇게 말합니다: "Your Google token or your password never reaches an agent or the model." (여러분의 Google token이나 비밀번호는 결코 에이전트나 모델에 닿지 않습니다.)

MCP Tools 페이지는 그 서버들을 밝힙니다: "The remote servers a person can connect today are GitHub and Carbon Forge (formerly Nuclear Notes)." (오늘 연결할 수 있는 원격 서버는 GitHub와 Carbon Forge(옛 Nuclear Notes)입니다.) 맞춤 SEAL 게이트웨이: 곧 제공 예정.

8단계. 거부 읽기

AEGIS by 100monkeys.ai(베타)가 호출을 거부하면, 클라이언트는 isError: true가 있는 평범한 도구 결과를 받으며 그 안에 error.code, error.message, request_id가 들어 있습니다. 닿는 범위에 관한 거부는 두 가지입니다:

CREDENTIAL_BINDING_REQUIRED: 아무것도 실행되기 전에 옵니다. 프로필이 없는 키에서는: "This key reaches none of your connections. Choose a profile for it on the API keys page in Zaru Web, or name one in the request." (이 키는 여러분의 어떤 연결에도 닿지 않습니다. Zaru Web의 API 키 페이지에서 프로필을 고르거나, 요청에서 하나를 지정하세요.) 한 번도 연결하지 않은 계열이라면 응답은 Connections 페이지를 알려 줍니다.
TOOL_NOT_IN_PROFILE: "This tool is not in the profile chosen for this conversation." (이 도구는 이 대화에 고른 프로필에 없습니다.)

둘 다 error.needs를 담아 계열과 그것을 해결하는 Zaru Web 페이지를 알려 줍니다. 실행의 경우 Zaru Web 카드에 "This run has no profile that names your <family>." (이 실행에는 여러분의 <family>를 지정한 프로필이 없습니다.)와 Open Profiles가 나옵니다. 정책 거부는 결정적이므로, 같은 호출을 반복하지 말고 호출을 바꾸세요.

9단계. 보류된 호출에 Zaru Web에서 답하기

"Every tool that asks for approval waits at the person's approval gate, as a call from the chat does." (승인을 요청하는 모든 도구는 채팅에서 온 호출처럼 그 사람의 승인 관문에서 기다립니다.) 호출은 {"status": "approval_pending", "approval_id", "summary", "message"}로 응답하며, 그 메시지는 "This waits for your answer in Zaru Web, under Approvals." (이것은 Zaru Web의 Approvals에서 여러분의 답을 기다립니다.)입니다. Approvals 페이지에서 답하세요. aegis.approval.status로 클라이언트에서 여러분의 답을 읽을 수 있습니다.

MCP Tools 페이지는 myzaru.com에서 기본으로 기다리는 호출을 나열합니다. 도구 카탈로그는 mail.send, mail.reply, mail.forward, mail.delete, mail.archive, 그리고 캘린더 쓰기 네 가지 calendar.create, calendar.update, calendar.delete, calendar.respond에 표시를 붙입니다. 배포 설정은 GitHub 쓰기 네 가지 github.merge_pull_request, github.push_files, github.create_or_update_file, github.delete_file와 함께 aegis.git.push, aegis.system.info에 표시를 붙입니다. "No Carbon Forge tool waits: neither the catalogue nor the configuration marks one, so a Carbon Forge call the key's profile admits runs at once." (Carbon Forge 도구는 기다리지 않습니다. 카탈로그도 설정도 표시를 붙이지 않으므로, 키의 프로필이 허용하는 Carbon Forge 호출은 바로 실행됩니다.) 프로필 양식은 기다리는 도구마다 "Needs your approval" (승인 필요) 표시를 붙입니다. 상시 "Always allow" (항상 허용)를 고르면 그 도구의 호출은 묻지 않고 처리되므로, 기다림은 기본값이지 약속이 아닙니다.