개발자 문서

MCP

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

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

시작하기

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

npx

npx altalt --mcp-only

1. OAuth로 연결하기(권장)

헤더 없이 엔드포인트만 등록하세요. 클라이언트가 Alt 인증 서버를 찾고 자동 등록한 뒤 브라우저 동의 화면을 엽니다.

Alt는 동적 클라이언트 등록(DCR)과 PKCE를 지원하므로 호환되는 클라이언트가 OAuth 설정을 자동으로 처리합니다.
브라우저에서 요청된 읽기 전용 권한과 연결할 워크스페이스를 확인한 뒤 접근을 승인하세요.
OAuth는 현재 Alt 관리자만 사용할 수 있습니다. 업그레이드 전에 만든 Alt OAuth 연결이 인증되지 않으면 클라이언트에서 제거한 뒤 한 번 다시 추가하세요.

2. 클라이언트 연결

OAuth 연결에는 URL만 입력하면 됩니다. OAuth 클라이언트 ID나 시크릿을 직접 만들 필요가 없습니다. 사용 중인 클라이언트가 OAuth를 지원하지 않을 때만 API 키를 사용하세요.

MCP URL

https://mcp.altalt.io/mcp

Claude / Claude Desktop / Cowork

Customize → Connectors → Add custom connector에서 위 URL을 입력하세요. OAuth client ID와 secret은 비워 두고 Connect를 선택하면 됩니다.

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를 반환하므로 에이전트가 나중에 다시 시도하면 됩니다.