개발자 문서

MCP

Claude, Codex 등 MCP 클라이언트를 Alt 노트에 연결하세요.

Alt가 운영하는 MCP(Model Context Protocol) 서버를 제공합니다. OAuth를 지원하는 클라이언트는 브라우저 로그인으로 연결하고, 지원하지 않는 클라이언트는 API 키를 사용할 수 있습니다. 두 방식 모두 동일한 읽기 전용 권한 범위(scope)와 워크스페이스 경계를 적용합니다.

시작하기

프로젝트 폴더에서 대화형 설정 도우미를 실행하세요. MCP 연결, API 키와 웹훅 확인, 코딩 에이전트 인계 과정을 차례로 안내합니다.

npx

npx altalt --mcp-only

Claude 커넥터로 연결

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 키를 사용하세요.

MCP URL

https://mcp.altalt.io/mcp

Claude / Claude Desktop / Cowork

사용자 정의 커넥터는 다른 Alt 환경에 연결할 때만 사용하세요. Customize → Connectors → Add custom connector에서 위 URL을 입력하고 OAuth client ID와 secret은 비워 둡니다.

Claude Code

shell

claude mcp add --transport http alt https://mcp.altalt.io/mcp

서버를 추가한 뒤 Claude Code에서 /mcp를 열고 Alt를 선택해 브라우저 인증을 완료하세요.

Codex CLI

shell

codex mcp add alt --url https://mcp.altalt.io/mcp
codex mcp login alt

config.toml

# ~/.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 키 설정을 사용하면 됩니다.

OAuth

{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp"
    }
  }
}

API 키

{
  "mcpServers": {
    "alt": {
      "url": "https://mcp.altalt.io/mcp",
      "headers": { "Authorization": "Bearer alt_live_..." }
    }
  }
}

자동화 도구와 이전 클라이언트에서는 API 키도 계속 사용할 수 있습니다. 계정 콘솔에서 키를 만들고 필요한 권한만 부여하세요. 공유 설정 파일에는 키를 직접 넣지 마세요. 자세한 내용은 보안 문서를 참고하세요.

3. 사용할 수 있는 도구

REST API와 같은 데이터를 읽는 도구 4개를 제공합니다. 각 도구에는 동일한 권한 범위(scope)가 적용됩니다.

list_notes — API 키로 볼 수 있는 노트 목록 — 커서 기반 페이지 나누기와 updated_after 필터를 지원합니다(notes:read).
get_note — 노트 하나의 기본 정보 — 제목, 전사·요약 준비 상태와 시간 정보를 반환합니다(notes:read).
get_note_transcript — 시간과 화자 이름이 표시된 구간으로 전체 전사를 반환합니다(transcripts:read).
get_note_summary — AI 요약을 Markdown으로 조회 (summaries:read).

노트는 녹음이 끝났거나 요약이 생성된 뒤에 나타납니다 — 메모만 있는 노트는 노출되지 않습니다. 콘텐츠가 준비되기 전에는 transcript_not_ready / summary_not_ready를 반환하므로 에이전트가 나중에 다시 시도하면 됩니다.