외부 서비스 연결하기

에이전트가 내 GitHub 저장소를 읽거나 Notion 페이지에 쓰려면 그 서비스의 로그인 정보가 필요합니다. UpServe는 이를 한 번만 연결해두면 되도록 설계되어 있습니다. 이후에 동일한 서비스를 쓰는 스킬을 설치할 때마다 다시 로그인할 필요가 없고, 에이전트가 작업할 때마다 자격증명이 자동으로 전달됩니다.

한눈에 보기

궁금한 점	답
어떤 서비스를 연결할 수 있나요?	GitHub, Linear, Notion, Slack, Google Drive, Google Calendar, Google Tasks
어디서 연결하나요?	(A) 마켓플레이스 → 스킬 에서 스킬 카드의 `연결 필요` 버튼, 또는 (B) 에이전트 설정 화면의 스킬 선택기에서 스킬을 켠 뒤 나타나는 연결 행의 `연결` 버튼
연결되면 뭐가 달라지나요?	그 서비스를 쓰는 스킬이 실행될 때 자격증명이 자동으로 주입됩니다. 매번 로그인하지 않아도 됩니다.
연결을 해제하려면?	마켓플레이스 → 스킬 에서 연결된 스킬 카드의 `연결 해제` 버튼을 사용합니다. 에이전트 설정 스킬 선택기의 OAuth 행에는 `다시 연결`(재인증)만 제공되며 해제 버튼은 없습니다.
서비스당 몇 개 계정을 연결할 수 있나요?	서비스당 1개 계정만 연결할 수 있습니다. 다른 계정으로 바꾸려면 기존 연결을 해제하고 새 계정으로 다시 연결하세요.
내 자격증명을 다른 사람도 쓸 수 있나요?	아니요. 자격증명은 본인 계정에서만 사용되며, 다른 사용자·다른 팀과 공유되지 않습니다.
토큰이 만료되면?	UpServe가 자동으로 갱신합니다. 외부 서비스에서 권한을 거둬간 경우에만 재연결 안내가 표시됩니다.

연결하는 방법

연결 진입점은 세 곳입니다. 어느 쪽을 사용해도 동일하게 연결됩니다.

경로 A — 마켓플레이스에서 연결

마켓플레이스 → 스킬 에서 GitHub·Linear·Notion·Slack 등 OAuth가 필요한 스킬을 엽니다.
스킬 카드에 연결 필요 표시가 보이면 그 옆 버튼을 클릭합니다.
외부 서비스의 로그인 창이 열립니다. 권한을 검토하고 승인하면 UpServe로 돌아옵니다.
카드에 연결된 계정 이름이 표시되면 완료입니다.


   [1] 마켓플레이스에서 스킬 열기
        예) "GitHub Integration"
              │
              ▼
   [2] 스킬 카드의 "연결 필요" 버튼 클릭
              │
              ▼
   [3] 외부 서비스 로그인 + 권한 승인
        (그 서비스의 공식 화면)
              │
              ▼
   [4] UpServe로 자동 복귀
        카드에 연결된 계정 이름이 표시됨

경로 B — 에이전트 설정에서 연결

스킬을 에이전트에 직접 장착하면서 바로 연결할 수 있습니다.

에이전트 페이지 → 설정 탭 → 스킬 선택기 를 엽니다.
연결이 필요한 스킬의 토글을 ON으로 켭니다.
스킬 카드 아래에 OAuth 행이 나타납니다. 버튼 상태는 다음과 같습니다.
- 연결 — 아직 연결되지 않은 상태. 클릭하면 외부 서비스 로그인 창이 열립니다.
- 연결 중... — 리디렉션 진행 중.
- 다시 연결 — 이미 연결되어 있거나 재인증이 필요한 상태. 클릭하면 다시 권한 승인 창이 열립니다.
- [서비스명] 연결됨 — 정상 연결 완료.
연결 을 눌러 외부 서비스의 권한을 승인하면 해당 스킬이 즉시 자격증명을 사용할 수 있게 됩니다.


   [1] 에이전트 설정 → 스킬 선택기
              │
              ▼
   [2] 스킬 토글 ON
              │
              ▼
   [3] OAuth 행 표시 — "연결" 버튼 클릭
              │
              ▼
   [4] 외부 서비스 로그인 + 권한 승인
              │
              ▼
   [5] 자동 복귀 — 연결 행에 "[서비스명] 연결됨" 표시

경로 C — 대화 중 연결 카드로 연결

가장 흔한 방법입니다. 에이전트가 아직 연결되지 않은 서비스를 써야 하는 작업을 만나면, 대화창에 바로 연결 카드를 띄웁니다.

작업 도중 에이전트가 채팅에 [서비스명] 연결 버튼이 있는 카드를 보여줍니다.
그 버튼을 누르면 외부 서비스의 로그인 창이 열립니다(경로 A·B와 동일한 권한 승인 흐름).
권한을 승인하고 돌아오면 에이전트가 중단했던 작업을 이어서 진행합니다.


   [1] 에이전트가 연결되지 않은 서비스를 필요로 함
              │
              ▼
   [2] 대화창에 "[서비스명] 연결" 카드 표시
              │
              ▼
   [3] 버튼 클릭 → 외부 서비스 로그인 + 권한 승인
              │
              ▼
   [4] 자동 복귀 — 에이전트가 작업을 이어서 진행

한 번 연결해 두면 같은 서비스를 쓰는 다른 스킬에도 동일한 자격증명이 그대로 적용됩니다. 예를 들어 GitHub을 한 번 연결하면, 나중에 GitHub을 쓰는 다른 스킬을 설치하거나 켤 때 다시 연결할 필요가 없습니다.

연결되면 무엇이 달라지나

에이전트가 그 서비스를 사용하는 스킬을 실행하면, UpServe가 유효한 액세스 토큰을 자동으로 가져와 스킬에 전달합니다.
토큰은 스킬 실행이 끝날 때 정리됩니다. 다음 실행 시점에 다시 가져옵니다.
만료가 임박한 토큰은 백그라운드에서 미리 갱신하므로, 작업 도중 끊기는 일이 거의 없습니다.
외부 서비스에서 권한을 직접 취소하거나 비밀번호 변경 등으로 토큰이 무효화된 경우에만 스킬 카드에 재연결 필요 안내가 표시됩니다. 그 부분을 클릭하면 다시 권한 승인 창이 열립니다.

연결 해제 / 재인증

연결 해제는 마켓플레이스 스킬 카드에서 할 수 있습니다. 연결된 스킬 카드에 계정 이름과 함께 연결 해제 버튼이 표시되며, 클릭하면 확인 후 즉시 해제됩니다.

에이전트 설정의 스킬 선택기 OAuth 행에는 다시 연결(재인증) 버튼만 있습니다. 이 버튼은 해제가 아니라 새로운 권한 승인 창을 여는 동작입니다. 해제가 필요하면 마켓플레이스 스킬 카드를 이용하세요.

해제 후 해당 서비스를 쓰는 스킬은 다음 실행에서 다시 연결을 요구합니다. 다른 계정으로 갈아끼우고 싶을 때는 한 번 해제하고 새 계정으로 연결하면 됩니다.

주의 — 연결을 해제하면 내 모든 에이전트에서 해당 서비스 기능이 동작하지 않게 됩니다. 자격증명은 내 계정에만 속하므로 다른 사용자나 팀원에게는 영향이 없습니다.

저장된 키 (직접 저장하는 자격 증명)

GitHub·Notion처럼 미리 만들어진 연결이 없는 서비스라도, API 키나 토큰을 직접 저장해 두면 에이전트가 계속 재사용할 수 있습니다. 예를 들어 결제 서비스 API 키를 한 번 저장해 두면, 그 에이전트가 매번 다시 물어보지 않고 작업에 사용합니다.

저장 방법 (대화 중) — 채팅 입력창의 자물쇠 버튼으로 값을 입력할 때 “이 에이전트가 나중에 재사용하도록 저장” 을 켜고 이름(예: STRIPE_API_KEY)을 붙이면 됩니다.
관리 — 설정 → 연결 의 저장된 키 섹션에서 에이전트별로 보고 삭제할 수 있습니다.
에이전트 전용 — 저장된 키는 그 에이전트만 사용합니다. 다른 에이전트·다른 사용자와 공유되지 않습니다.
다시 표시되지 않음 — 저장한 값은 보안을 위해 다시 보여주지 않습니다. 바꾸려면 삭제하고 새로 저장하세요.
자동 갱신 없음 — 위의 OAuth 연결과 달리, 직접 저장한 키는 자동으로 갱신되지 않습니다. 만료되면 직접 교체해야 합니다.

일회성 비밀 (저장하지 않는 값)

비밀번호·인증 코드처럼 쓰고 남기지 않을 값은, 채팅 입력창의 자물쇠 버튼으로 보내되 저장 옵션을 끄면 됩니다. 입력하신 평문 값은 저장되지 않으며, 암호화된 값은 잠시 후(최대 15분) 자동으로 삭제됩니다. 대화에는 라벨과 가려진 자리표시자만 남습니다.

보안

사용자 단위 분리 — 자격증명은 본인 계정에 묶여 저장되며, 다른 사용자나 같은 팀의 다른 멤버가 가져갈 수 없습니다.
저장된 키는 에이전트 단위 분리 — 직접 저장한 키는 그 에이전트 전용으로 암호화 저장되며, 공유 링크로 들어온 외부 방문자에게는 절대 노출되지 않습니다.
에이전트는 직접 토큰을 보지 않음 — 토큰은 스킬 실행 환경에 환경변수로만 잠깐 전달되며, 실행이 끝나면 정리됩니다. 채팅 메시지나 로그에는 노출되지 않습니다.
암호화 저장 — 액세스 토큰과 리프레시 토큰은 모두 암호화되어 데이터베이스에 저장됩니다.
표준 OAuth + CSRF 방지 — 표준 Authorization Code 흐름을 사용하며 위조된 콜백은 거부됩니다.

고급 (Advanced)

아래는 일반 사용자가 알 필요 없는 내부 동작입니다. 직접 스킬을 만들거나 통합 동작을 디버깅할 때 참고하세요.

어떤 권한을 요청하나

UpServe가 연결 시 사용자 관점에서 요청하는 권한은 대체로 다음 범위입니다(실제 화면은 각 서비스 정책에 따름).

서비스	요청하는 권한 (사용자 관점 요약)
GitHub	내 저장소(공개·비공개) 코드·이슈·PR 읽기·쓰기, 조직 멤버십·팀 정보 읽기, 프로필 정보 읽기
Linear	내 워크스페이스의 이슈·프로젝트·코멘트 읽기 및 작성, 이슈 생성
Notion	Notion 동의 화면에서 사용자가 직접 선택한 페이지·데이터베이스에만 접근 (읽기·쓰기). 어떤 페이지를 공유할지는 Notion 플랫폼이 결정하며, UpServe는 선택된 범위만 사용합니다.
Slack	내 워크스페이스 공개 채널·프라이빗 채널·1:1 DM 메시지 읽기, 봇으로 메시지 전송, 사용자·팀 정보 읽기
Google Drive / Calendar / Tasks	해당 서비스의 파일·일정·할 일 읽기 및 쓰기 (Google Drive는 Picker로 사용자가 직접 선택한 파일에만 접근)

권한 화면은 항상 외부 서비스의 공식 동의 화면이며, UpServe가 받은 권한 범위는 연결 정보에 그대로 기록됩니다.

스킬이 자격증명을 어떻게 받아 쓰나

스킬을 직접 만들거나 외부에서 가져온 스킬의 내부 동작을 살펴봐야 할 때만 알면 됩니다. 스킬의 SKILL.md가 metadata.requires로 어떤 자격증명을 어떤 환경변수 이름으로 받을지 선언하고, 실행 시점에 UpServe가 유효한 토큰(만료 임박이면 자동 갱신)을 그 환경변수로 주입한 뒤 실행이 끝나면 정리합니다. 에이전트가 스킬을 패키징할 때 이 항목을 자동으로 채우므로 사용자가 직접 yaml을 손볼 일은 없습니다. 매핑 표·예시는 스킬 생성하기 → 시크릿 주입을 참고하세요.

Google Drive Picker

스킬이나 에이전트 동작에서 Google Drive 파일에 접근해야 할 때, UpServe는 Google Picker를 사용합니다. Google Picker는 사용자 본인의 Google 계정으로 브라우저 안에서 실행되는 파일 선택기입니다. 사용자가 Picker를 통해 직접 선택한 파일에만 접근할 수 있으며, Drive 전체에 대한 접근 권한은 요청하지 않습니다. 이는 앱이 열거나 생성한 파일로만 범위가 제한되는 권한 방식으로 강제됩니다.

토큰 만료와 자동 갱신

액세스 토큰의 만료 시각이 임박하면(만료 5분 전), UpServe가 저장된 리프레시 토큰으로 자동 갱신합니다.
갱신은 스킬 실행 직전에 일어나므로, 작업 도중 끊김 없이 새 토큰이 적용됩니다.
외부 서비스에서 사용자가 직접 권한을 취소하거나 리프레시 토큰이 폐기된 경우, 갱신이 실패하고 연결이 inactive 상태로 표시됩니다. 이때 카드에 재연결 필요가 떠서 사용자가 한 번 더 권한을 승인하도록 안내합니다.