개발자 문서
MCP
Claude, Codex 등 MCP 클라이언트를 Alt 노트에 연결하세요.
Alt가 운영하는 MCP(Model Context Protocol) 서버를 제공합니다. OAuth를 지원하는 클라이언트는 브라우저 로그인으로 연결하고, 지원하지 않는 클라이언트는 API 키를 사용할 수 있습니다. 두 방식 모두 동일한 읽기 전용 권한 범위(scope)와 워크스페이스 경계를 적용합니다.
시작하기
프로젝트 폴더에서 대화형 설정 도우미를 실행하세요. MCP 연결, API 키와 웹훅 확인, 코딩 에이전트 인계 과정을 차례로 안내합니다.
npx altalt --mcp-onlyClaude 커넥터로 연결
Alt는 Claude 커넥터 디렉터리에 등록돼 있어, 대부분의 경우 아래 엔드포인트를 직접 다룰 일이 없습니다. Claude에서 Customize → Connectors를 열고 Alt를 검색해 Connect를 선택하세요.
- Alt 동의 화면에서 접근을 승인하고, 커넥터가 읽을 콘텐츠 범위를 고릅니다 — 개인 노트 또는 채널 하나입니다.
- 입력할 주소도, 발급할 API 키도 없습니다. Claude가 OAuth로 알아서 등록합니다.
- 유료 플랜의 Alt 계정이 필요합니다. 무료 계정은 동의 화면까지는 열리지만 승인할 때
plan_required오류를 받습니다. - 설계상 읽기 전용입니다. 노트를 나열·검색하고 전사·요약을 읽을 뿐 쓰지 않습니다. 계정 콘솔에서 언제든 해제할 수 있습니다.
1. OAuth로 연결하기(권장)
헤더 없이 엔드포인트만 등록하세요. 클라이언트가 Alt 인증 서버를 찾고 자동 등록한 뒤 브라우저 동의 화면을 엽니다.
- Alt는 동적 클라이언트 등록(DCR)과 PKCE를 지원하므로 호환되는 클라이언트가 OAuth 설정을 자동으로 처리합니다.
- 브라우저에서 요청된 읽기 전용 권한과 연결할 워크스페이스를 확인한 뒤 접근을 승인하세요.
- 연결하려면 유료 플랜의 Alt 계정이 필요합니다. 무료 계정은 동의 화면까지는 열리지만 승인할 때
plan_required오류를 받습니다.
2. 클라이언트 연결
OAuth 연결에는 URL만 입력하면 됩니다. OAuth 클라이언트 ID나 시크릿을 직접 만들 필요가 없습니다. 사용 중인 클라이언트가 OAuth를 지원하지 않을 때만 API 키를 사용하세요.
https://mcp.altalt.io/mcpClaude / Claude Desktop / Cowork
사용자 정의 커넥터는 다른 Alt 환경에 연결할 때만 사용하세요. Customize → Connectors → Add custom connector에서 위 URL을 입력하고 OAuth client ID와 secret은 비워 둡니다.
Claude Code
claude mcp add --transport http alt https://mcp.altalt.io/mcp서버를 추가한 뒤 Claude Code에서 /mcp를 열고 Alt를 선택해 브라우저 인증을 완료하세요.
Codex CLI
codex mcp add alt --url https://mcp.altalt.io/mcp
codex mcp login alt# ~/.codex/config.toml
[mcp_servers.alt]
url = "https://mcp.altalt.io/mcp"서버를 추가하면 일반적으로 브라우저 인증까지 완료됩니다. 인증이 시작되지 않을 때만 codex mcp login alt를 실행하세요.
Cursor
Cursor에 추가URL만 등록하는 원클릭 설치입니다. Cursor MCP 설정에서 Connect 또는 Needs authentication을 선택한 뒤 브라우저 동의 화면에서 접근을 승인하세요.
기타 클라이언트와 API 키 대체 방식
먼저 URL만 있는 OAuth 설정을 사용하세요. 클라이언트가 MCP OAuth를 지원하지 않으면 Bearer API 키 설정을 사용하면 됩니다.
{
"mcpServers": {
"alt": {
"url": "https://mcp.altalt.io/mcp"
}
}
}{
"mcpServers": {
"alt": {
"url": "https://mcp.altalt.io/mcp",
"headers": { "Authorization": "Bearer alt_live_..." }
}
}
}자동화 도구와 이전 클라이언트에서는 API 키도 계속 사용할 수 있습니다. 계정 콘솔에서 키를 만들고 필요한 권한만 부여하세요. 공유 설정 파일에는 키를 직접 넣지 마세요. 자세한 내용은 보안 문서를 참고하세요.
3. 사용할 수 있는 도구
읽기 전용 도구 7개를 제공합니다. 각 도구에는 REST API와 같은 권한 범위(scope)가 적용됩니다.
list_notes— 이 연결로 읽을 수 있는 노트 목록 — 커서 기반 페이지 나누기를 지원합니다. 기본은 수정 시각이 오래된 순서이고,order=newest_first를 주면 최근 순서로 받습니다.updated_after, 녹음 종료 시각(ended_after/ended_before),channel_id,folder_id로 거를 수 있습니다(notes:read).get_note— 노트 하나의 기본 정보 — 제목, 전사·요약 준비 상태와 시간 정보를 반환합니다(notes:read).get_note_transcript— 시간과 화자 이름이 표시된 구간으로 전체 전사를 반환합니다(transcripts:read).get_note_summary— AI 요약을 Markdown으로 조회 (summaries:read).search_notes— 제목·전사·요약에 단어나 문구가 들어 있는 노트를 찾습니다. 한국어도 검색됩니다. 전사에서 찾으면 시간과 화자를 함께 반환합니다. 전사와 요약은transcripts:read/summaries:read권한이 있을 때만 검색합니다(notes:read).list_folders— 이 연결로 읽을 수 있는 폴더 목록 — 폴더 id를list_notes의folder_id에 넣으면 그 폴더의 노트만 받습니다(notes:read).get_account_info— 이 연결이 어떤 Alt 계정에 속하는지, 개인 노트·채널 하나·워크스페이스 전체 중 무엇을 읽는지, 읽을 수 있는 채널과 권한을 보여 줍니다. 노트가 보이지 않을 때 확인하세요(notes:read).
노트는 녹음이 끝났거나 요약이 생성된 뒤에 나타납니다 — 메모만 있는 노트는 노출되지 않습니다. 콘텐츠가 준비되기 전에는 transcript_not_ready / summary_not_ready를 반환하므로 에이전트가 나중에 다시 시도하면 됩니다.