MCP 서버
Claude, Claude Code, Cursor 같은 AI 클라이언트를 Onttle MCP 서버에 연결해 Project를 조회하고 변경하는 방법을 설명합니다.
Onttle MCP 서버는 AI 클라이언트가 Onttle Project를 직접 다룰 수 있게 해 주는 Model Context Protocol 서버입니다. 연결하면 AI가 테이블 구조와 콘텐츠를 읽고, 사용자의 확인을 받은 뒤 콘텐츠·테이블·설정을 변경할 수 있습니다.
https://api.onttle.com/mcp
전송 방식은 Streamable HTTP이며, 별도로 설치할 프로그램은 없습니다.
연결 방식
두 가지 자격 증명 중 하나로 연결합니다.
| 방식 | 접근 범위 | 적합한 경우 |
|---|---|---|
| Onttle 계정 로그인 | 계정이 속한 모든 Project. Project마다 본인 역할이 적용됩니다 | Claude 앱, 여러 Project를 오가는 작업 |
게시용 키 (pk-proj_…) |
키가 속한 Project 하나. 공개 API가 제공하는 데이터만 읽기 | 스키마와 발행된 콘텐츠만 읽으면 되는 경우 |
시크릿 키 (sk-proj_…) |
키가 속한 Project 하나. 초안·파일·로그 읽기와 콘텐츠 쓰기 | CI, 서버에서 실행하는 에이전트 |
테이블 생성·수정, 권한 규칙, API Key 발급, 회원 관리는 계정 로그인으로만 할 수 있습니다. API Key는 누가 변경했는지를 Audit 로그에 남길 수 없기 때문입니다.
연결하기
Claude Code
계정 로그인
claude mcp add --transport http onttle https://api.onttle.com/mcp
Claude Code를 실행하고 /mcp를 입력한 뒤 onttle → Authenticate를 선택합니다. 브라우저에서 Onttle에 로그인하고 동의 화면에서 승인을 누르면 연결됩니다.
API Key
claude mcp add --transport http onttle https://api.onttle.com/mcp --header "X-Onttle-Key: $ONTTLE_API_KEY"
Claude 커넥터 (웹·데스크톱·모바일)
Claude 앱에서는 Onttle을 커스텀 커넥터로 추가합니다. 한 번 추가하면 같은 계정의 웹, 데스크톱, 모바일 앱에서 모두 쓸 수 있습니다. 커스텀 커넥터는 Claude 유료 플랜에서 제공됩니다.
1. 커넥터 추가
- Claude에서 설정 > 커넥터를 엽니다.
- 커스텀 커넥터 추가를 누릅니다.
- 이름에
Onttle, 원격 MCP 서버 URL에 아래 주소를 입력하고 추가를 누릅니다.
https://api.onttle.com/mcp
Team·Enterprise 플랜에서는 조직 소유자가 조직 설정 > 커넥터에서 먼저 추가해야 합니다. 그 뒤 구성원이 각자 자신의 설정에서 연결합니다.
2. Onttle 계정 연결
- 커넥터 목록의 Onttle에서 연결을 누릅니다.
- 브라우저에 Onttle 로그인 화면이 열리면 로그인합니다.
- 동의 화면에서 요청한 앱 이름이 Claude인지 확인하고 승인을 누릅니다.
연결은 로그인한 Onttle 계정의 권한을 그대로 따릅니다. 구성원마다 자기 계정으로 연결하므로, 같은 조직이라도 각자 접근할 수 있는 Project만 보입니다.
3. 대화에서 사용
- 새 대화의 입력창에서 검색 및 도구 메뉴를 열고 Onttle을 켭니다.
- "내 Onttle 프로젝트 목록을 보여 줘"처럼 요청합니다. Claude가
onttle_list_workspaces와onttle_list_projects를 호출합니다. - 도구를 처음 호출할 때 Claude가 허용 여부를 묻습니다. 읽기 도구는 항상 허용으로 두어도 되고, 쓰기 도구는 매번 확인하도록 두는 것을 권합니다.
쓰기 도구는 Claude의 확인과 별개로 두 번 호출해야 적용됩니다. Claude가 보여 주는 미리보기를 확인한 뒤 진행하라고 답하면 됩니다.
알아 둘 점
- Claude 앱은 계정 로그인으로만 연결됩니다. API Key 헤더는 설정할 수 없습니다.
- Workspace에 IP 접근 규칙이 있으면 Anthropic의 발신 대역을 허용해야 합니다.
- 연결을 끊으려면 설정 > 커넥터에서 Onttle의 연결을 해제하거나 커넥터를 제거합니다.
그 밖의 클라이언트
원격 MCP 서버(Streamable HTTP)를 지원하는 클라이언트라면 연결할 수 있습니다. 설정 파일을 쓰는 클라이언트(예: Cursor)는 다음과 같이 등록합니다.
{
"mcpServers": {
"onttle": {
"url": "https://api.onttle.com/mcp",
"headers": {
"X-Onttle-Key": "sk-proj_..."
}
}
}
}
headers를 빼면 OAuth를 지원하는 클라이언트는 계정 로그인 흐름으로 연결합니다. API Key는 X-Onttle-Key 헤더 대신 Authorization: Bearer <API Key>로 보내도 됩니다.
권한
도구 목록은 모든 연결에 똑같이 보이고, 권한은 호출할 때마다 확인합니다.
- 계정 로그인: Project 도구를 호출할 때
project_id로 대상을 지정합니다. 그 Project에서의 본인 역할(OWNER,ADMIN,EDITOR,GUEST)이 도구의 최소 역할보다 낮으면 거부됩니다. 역할별 권한은 멤버 권한을 참고하세요. - 게시용 키:
GUEST수준으로 동작하며, 발행된 콘텐츠처럼 공개 API가 제공하는 데이터만 반환합니다. - 시크릿 키:
EDITOR수준으로 동작합니다.project_id를 지정할 필요가 없습니다.
API Key의 만료, 허용 호스트, Workspace IP 접근 규칙은 REST API와 똑같이 적용됩니다.
변경은 두 번 호출해야 적용됩니다
데이터를 변경하는 도구는 한 번의 호출로 실행되지 않습니다.
- 처음 호출하면 아무것도 바꾸지 않고, 바뀔 내용의 미리보기와
confirm_token을 돌려줍니다. - AI가 미리보기를 사용자에게 보여 줍니다.
- 사용자가 동의하면 같은 인자에
confirm_token을 더해 다시 호출합니다. 이때 변경이 적용됩니다.
confirm_token은 10분 동안 유효하고, 발급받은 연결·도구·Project·인자에 묶여 있습니다. 인자를 하나라도 바꾸면 토큰이 맞지 않아 거부되므로, 미리보기에서 본 내용과 다른 변경이 적용될 수 없습니다.
도구
도구는 읽기 23개, 쓰기 20개입니다. 최소 역할은 계정 로그인일 때 필요한 Project 역할이고, API Key는 그 도구를 호출할 수 있는 키 유형입니다. -는 계정 로그인으로만 호출할 수 있다는 뜻입니다.
Workspace와 Project
| 도구 | 종류 | 설명 | 최소 역할 | API Key |
|---|---|---|---|---|
onttle_list_workspaces |
읽기 | 계정이 속한 Workspace 목록 | - | - |
onttle_list_projects |
읽기 | Workspace의 Project 목록 | - | - |
onttle_get_project |
읽기 | Project 정보 | GUEST | 게시용 |
onttle_get_schema |
읽기 | 테이블과 Column 구조 | GUEST | 게시용 |
onttle_get_openapi_spec |
읽기 | Project의 OpenAPI 명세 | GUEST | 게시용 |
onttle_create_table |
쓰기 | 테이블 생성 | ADMIN | - |
onttle_update_table |
쓰기 | 테이블과 Column 수정 | ADMIN | - |
onttle_set_table_rules |
쓰기 | 테이블 권한 규칙 설정 | ADMIN | - |
콘텐츠
| 도구 | 종류 | 설명 | 최소 역할 | API Key |
|---|---|---|---|---|
onttle_search_contents |
읽기 | 콘텐츠 검색·필터·정렬 | GUEST | 게시용 |
onttle_get_contents |
읽기 | 콘텐츠 한 건 조회 | GUEST | 게시용 |
onttle_create_contents |
쓰기 | 콘텐츠 생성 | EDITOR | 시크릿 |
onttle_update_contents |
쓰기 | 콘텐츠 수정 | EDITOR | 시크릿 |
onttle_set_contents_status |
쓰기 | 발행 / 발행 취소 | EDITOR | 시크릿 |
onttle_delete_contents |
쓰기 | 콘텐츠 삭제 | EDITOR | 시크릿 |
onttle_get_contents_history |
읽기 | 버전 기록 조회 | EDITOR | 시크릿 |
onttle_rollback_contents |
쓰기 | 이전 버전으로 되돌리기 | EDITOR | 시크릿 |
게시용 키로 콘텐츠를 조회하면 발행된 콘텐츠만 반환합니다.
- 값의 키: 조회 결과의
data와 쓰기 도구의data는 모두 Column 이름을 키로 씁니다. 읽은 값을 그대로 쓰기에 넣을 수 있습니다. - EDITOR Column: Markdown 문자열 또는 TipTap 문서(JSON 객체나 JSON 문자열)를 보냅니다. 대시보드와 REST API도 같은 형식을 받습니다. 다국어 Column은
{ "ko": 값, "en": 값 }처럼 언어별로 보냅니다. 조회 결과에는 본문이 일반 텍스트로 나옵니다. - 미리보기 검증: 생성·수정 미리보기가 필수값, 길이·범위 같은 Column 제약을 미리 검사해
invalid_rows로 알려 줍니다. 모든 행이 실패하면confirm_token을 발급하지 않습니다. - 수정과 롤백: 대시보드와 같은 로직으로 동작합니다. 수정한 행은
publish: true를 주지 않으면 DRAFT로 저장되고, 롤백한 행은 되돌린 버전의 값과 상태를 그대로 가져옵니다. 발행된 행을 초안이던 버전으로 되돌리면 상태가 DRAFT가 되며, 미리보기에 롤백 후 상태가 표시됩니다.
리소스
| 도구 | 종류 | 설명 | 최소 역할 | API Key |
|---|---|---|---|---|
onttle_list_categories |
읽기 | 카테고리 목록 | GUEST | 시크릿 |
onttle_create_categories, onttle_update_categories |
쓰기 | 카테고리 생성·수정 | EDITOR | 시크릿 |
onttle_list_translations |
읽기 | 번역 목록 | GUEST | 시크릿 |
onttle_create_translations, onttle_update_translations |
쓰기 | 번역 생성·수정 | EDITOR | 시크릿 |
onttle_list_variables |
읽기 | 변수 목록 | GUEST | 시크릿 |
onttle_create_variables, onttle_update_variables |
쓰기 | 변수 생성·수정 | EDITOR | 시크릿 |
onttle_search_files |
읽기 | 업로드한 파일 검색 | GUEST | 시크릿 |
onttle_list_webhooks |
읽기 | Webhook 목록 | GUEST | 시크릿 |
onttle_create_webhook |
쓰기 | Webhook 생성 | EDITOR | 시크릿 |
onttle_get_webhook_logs |
읽기 | Webhook 발송 기록 | EDITOR | 시크릿 |
회원
| 도구 | 종류 | 설명 | 최소 역할 | API Key |
|---|---|---|---|---|
onttle_get_member_settings |
읽기 | 회원 기능 설정 조회 | GUEST | 시크릿 |
onttle_update_member_settings |
쓰기 | 회원 기능 설정 변경 | ADMIN | - |
onttle_get_member_stats |
읽기 | 가입·활성 회원 통계 | EDITOR | - |
onttle_list_members |
읽기 | 회원 목록 | EDITOR | - |
onttle_update_member |
쓰기 | 회원 정보·상태 수정 | EDITOR | - |
onttle_create_member |
쓰기 | 회원 직접 추가 | ADMIN | - |
onttle_create_member는 가입 1건으로 과금되고 월간 가입 한도에 포함됩니다. 회원 기능은 회원 문서를 참고하세요.
API와 운영
| 도구 | 종류 | 설명 | 최소 역할 | API Key |
|---|---|---|---|---|
onttle_list_api_keys |
읽기 | API Key 목록 (전체 값은 표시하지 않음) | ADMIN | - |
onttle_create_api_key |
쓰기 | 게시용 API Key 발급 | ADMIN | - |
onttle_get_api_settings |
읽기 | API 엔드포인트 설정 조회 | GUEST | 시크릿 |
onttle_set_api_settings |
쓰기 | API 엔드포인트 설정 변경 | ADMIN | - |
onttle_analyze_api_logs |
읽기 | API 요청 로그 분석 | EDITOR | 시크릿 |
onttle_get_billing_summary |
읽기 | 플랜과 사용량 요약 | EDITOR | - |
onttle_create_api_key는 게시용 키만 발급합니다. 전체 키 값은 확인된 호출의 결과에 한 번만 표시됩니다. 시크릿 키는 대시보드에서만 발급할 수 있습니다.
문서
| 도구 | 종류 | 설명 | 최소 역할 | API Key |
|---|---|---|---|---|
onttle_search_docs |
읽기 | Onttle 공식 문서와 FAQ 검색 | - | 게시용 |
onttle_get_api_reference |
읽기 | Project에 맞춘 REST API 레퍼런스 | GUEST | 게시용 |
onttle_search_docs는 연결만 되어 있으면 역할과 관계없이 호출할 수 있습니다.
프롬프트와 리소스
프롬프트를 지원하는 클라이언트에서는 다음 작업을 바로 시작할 수 있습니다.
| 프롬프트 | 용도 |
|---|---|
onttle-setup |
현재 코드베이스에 Onttle 연동 코드를 추가합니다 |
onttle-add-auth |
회원 가입·로그인을 추가합니다 |
onttle-seed |
로컬 데이터를 초안 콘텐츠로 가져옵니다 |
onttle-debug |
Onttle API 연동 문제의 원인을 찾습니다 |
리소스로는 다음 세 가지를 제공합니다.
| 리소스 URI | 내용 |
|---|---|
onttle://docs/get-started |
AI 에이전트용 시작 가이드 |
onttle://projects/{projectId}/schema |
Project의 테이블·Column 구조 |
onttle://projects/{projectId}/openapi.json |
Project의 OpenAPI 명세 |
사용량과 제한
- API Key 연결: 도구 호출 한 번이 API 읽기 1건으로, 확인된 쓰기 한 번이 API 쓰기 1건으로 기록됩니다. 사용량 화면에는
/mcp/tools/<도구 이름>경로로 표시됩니다. - 계정 연결: 과금하지 않습니다. 호출은 Project의 API 로그에
/mcp/tools/<도구 이름>경로로 기록되고, API 키 열에는 "계정 연결 (MCP)"로 표시됩니다. Workspace·Project 목록 조회와 문서 검색처럼 특정 Project에 속하지 않는 호출은 기록하지 않습니다. 관리 도구로 한 변경은 Audit 로그에도 남습니다. - 요청 한도: 플랜의 API 요청 한도가 그대로 적용됩니다. 확인된 쓰기는 연결당 분당 30회로 제한됩니다.
- 결과 크기: 도구 결과가 48,000자를 넘으면
result_too_large오류와 함께 범위를 좁히는 방법을 안내합니다. 필터를 추가하거나 페이지 크기를 줄여 다시 호출하세요.
IP 접근 규칙을 쓰는 Workspace
Claude 앱(웹·데스크톱·모바일)의 요청은 사용자의 컴퓨터가 아니라 Anthropic의 서버에서 나옵니다. Workspace에 IP 접근 규칙이 있다면 Anthropic의 발신 대역을 허용 목록에 추가해야 Claude 앱에서 연결할 수 있습니다.
160.79.104.0/21
Claude Code처럼 사용자의 컴퓨터에서 실행되는 클라이언트는 그 컴퓨터의 IP로 요청합니다.
허용 호스트를 도메인으로만 제한한 API Key는 MCP에서 쓸 수 없습니다. MCP 클라이언트는 Origin 헤더를 보내지 않기 때문입니다. 허용 호스트가 없는 키나 IP를 허용한 키를 쓰거나, 계정 로그인으로 연결하세요.
기록
MCP로 실행한 변경은 대시보드에서 한 변경과 똑같이 Audit 로그에 남습니다. 계정 연결로 실행한 관리 작업은 mcp.tool_called 이벤트로 기록되고, 변경 행에는 경로가 mcp로 표시됩니다.
연결 해제
- Claude Code:
claude mcp remove onttle - Claude 앱: 설정 > 커넥터에서 Onttle 커넥터를 제거합니다.
- API Key: 대시보드의 API Keys에서 키를 삭제하면 그 키를 쓰는 모든 연결이 즉시 끊깁니다.
자주 만나는 오류
| 오류 | 원인 | 해결 |
|---|---|---|
401 Unauthorized |
자격 증명이 없거나 만료됨 | 클라이언트에서 다시 인증하거나 API Key를 확인합니다 |
forbidden |
역할이 부족하거나 그 키 유형으로 호출할 수 없음 | 도구 표의 최소 역할과 API Key 열을 확인합니다 |
confirm_token_expired |
미리보기 후 10분이 지남 | confirm_token 없이 다시 호출해 새 미리보기를 받습니다 |
confirm_token_invalid |
미리보기와 인자가 다름 | 같은 인자로 다시 호출하거나 새 미리보기를 받습니다 |
result_too_large |
결과가 48,000자를 넘음 | 필터를 추가하거나 페이지 크기를 줄입니다 |
| IP가 허용되지 않았다는 메시지 | Workspace IP 접근 규칙 | 요청 IP 또는 160.79.104.0/21을 허용 목록에 추가합니다 |
429 Too Many Requests |
요청 한도 초과 | Retry-After 헤더의 시간만큼 기다린 뒤 다시 시도합니다 |
다음 단계
- 인증 — API Key를 발급하고 허용 호스트와 만료를 설정합니다.
- 멤버 권한 — 역할별로 할 수 있는 작업을 확인합니다.
- Ask AI (Assistant) — 대시보드 안에서 같은 도구를 쓰는 AI 어시스턴트입니다.