처음부터 끝까지
도구를 쓰는 순서. 무엇부터 부를지 모를 때 이것부터 읽으세요.
처음부터 끝까지
이 서버로 할 수 있는 일의 순서예요. 각 단계에 쓰는 도구를 함께 적었어요.
1. 어디에 있는지 확인
whoami가 이 토큰이 누구의 것이고 읽기만 되는지 쓰기도 되는지 알려줘요.
list_projects가 프로젝트와 각각의 주소, 그리고 다른 모든 도구에 넣을 ID(ref)를 줘요.
프로젝트가 없으면 create_project로 만들어요. 데이터베이스·인증·파일 저장소가 한 번에 만들어져요.
리전은 만들 때 정하고 나중에 바꿀 수 없어요. list_regions로 쓸 수 있는 곳을 먼저 보세요.
비우면 기본 리전에 만들어요. 요금은 리전과 상관없이 같으니 고객과 가까운 곳을 고르면 돼요.
list_regions의 can_create가 false인 곳은 아직 서버나 데이터베이스 자리가 없어 만들 수 없어요. 대신 request_region으로 요청하세요.
담당자가 직접 연락해요. 어디에 무엇을 두려는지 적으면 그 내용부터 읽어요. 날짜는 약속하지 않아요.
급하면 열린 리전에 만들어 써도 되지만, 나중에 옮길 수는 없고 새로 만들어야 해요.
list_server_sizes는 서버 크기마다 지역별 월 금액을 줘요(통화를 비우면 조직의 결제 통화). 보기만 하는 도구예요.
2. 지금 무엇이 있는지 확인
list_tables가 표와 각 표의 칸, 대략의 줄 수, 그리고 접근 규칙이 켜져 있는지와 규칙이 몇 개인지를 줘요.
규칙 수가 0인 표는 공개 키로 아무것도 보이지 않아요. 이 숫자가 0인 표를 먼저 찾으세요.
list_users는 그 프로젝트를 쓰는 서비스의 가입자예요. 플랫폼 계정(당신)과는 별개예요.
한 번에 다 오지 않아요. total이 전체 인원이고, has_more가 true면 offset을 올려 다시 부르세요.
users의 길이를 인원수로 쓰면 틀려요.
list_buckets는 파일 저장소, usage는 이번 달 사용량이에요.
프로젝트를 만든 직후 몇 초는 데이터베이스가 아직 없을 수 있어요.
그동안 다른 도구는 "아직 만들고 있어요"로 거절해요. 기다렸다 다시 부르세요.
"만들지 못했어요"가 나오면 retry_provisioning으로 다시 시도하세요.
어느 쪽이든 프로젝트를 새로 만들지 마세요. 요금만 두 배가 돼요.
쓰지 않는 프로젝트는 pause_project로 멈추고 resume_project로 다시 켜요. 멈춘 동안 사이트·API·함수는 503
(project_paused)을 응답하고 예약 작업이 돌지 않지만, 데이터는 그대로예요.
무료 요금제가 3일 동안 쓰지 않아 멈춘 프로젝트도 resume_project(또는 새 배포)로 다시 켜요.
데이터베이스를 쓸 수 없는 상태(결제 실패, 무료 요금제, 일시정지)가 90일 이어지면 데이터베이스를 서버에서 꺼내 보관 저장소로 옮겨요.
list_projects의 archive_at이 옮기는 때이고, get_project_archive가 이유와 날짜를 알려줘요. 옮기기 30·7·1일 전에 메일이 가요.
옮긴 뒤 1년 동안은 restore_project_archive로 그대로 복원하고(결제나 요금제 문제가 먼저 풀려야 해요), create_archive_download_url로 보관 파일을 내려받아요.
그동안 다른 도구는 "보관 저장소에 있어요"로 거절하고, API는 503(project_archived)을 응답해요. 1년이 지나면 보관 파일과 파일을 지워요.
ORM이나 마이그레이션 도구(Prisma, Drizzle, psql)를 쓰려면 get_database_connection으로 주소를 받고
reset_database_password로 비밀번호를 만드세요(한 번만 보여 줘요). 5432는 세션, 6543은 트랜잭션 풀러이며 TLS만 받아요.
배포한 앱이 DATABASE_URL을 읽는다면 keep_for_deploys: true로 만드세요. 비밀번호를 암호화해 저장하고, 운영 서버·미들웨어·함수가 실행될 때 DATABASE_URL(6543)·POSTGRES_URL(6543)·DIRECT_URL(5432)로 받아요. 빌드에는 넘기지 않아요. 배포한 코드가 행 수준 보안을 거치지 않고 모든 행을 읽게 되니 사용자가 원할 때만 켜세요. 이 옵션 없이 다시 만들면 넘기던 것도 멈추고, 실행 중인 운영 서버는 다시 시작하거나 다시 배포해야 새 값을 받아요.
백업은 매일 밤 프로젝트 리전 시각 03:00~05:00에 자동으로 만들어져요(list_backups). 마이그레이션이나 대량 삭제 전에는 create_backup으로 직접 만드세요.
restore_backup은 그 시점으로 표·가입자·파일을 되돌려요. 직전 상태를 먼저 백업하니 잘못 되돌려도 다시 복원할 수 있어요.
delete_project는 데이터를 영구히 지워요. 사용자가 분명히 요청했을 때만, confirm에 프로젝트 이름을 넣어 부르세요.
3. 만들기
표는 run_sql, 규칙도 run_sql, 확인은 read_rows나 query_sql.
query_sql은 조회 한 문장만 읽기 전용으로 실행해요. 읽기 토큰으로도 부를 수 있고, Vault의 비밀 값은 열지 않아요.
읽기 토큰에는 배포 훅 주소(list_deploy_hooks)를 가려서 줘요(secret_hidden). 데이터베이스 웹훅·로그 내보내기·알림 채널의 서명 키는 토큰과 상관없이 만들 때 한 번만 보여주고, 목록에는 끝 네 글자(signing_secret_last4)만 나와요.
버킷은 create_bucket, 시험 가입자는 add_user.
앱에 넣을 주소와 키는 get_project_keys. 프런트엔드 코드에는 only: "publishable"로 받은 주소와 공개 키만 넣어요.
연결 주소의 옵션
연결 주소 뒤에 옵션을 붙이면 보이는 도구와 할 수 있는 일이 줄어요. 목록에 없는 도구는 이름으로 불러도 서버가 거절해요. 지금 무엇이 켜져 있는지는 whoami의 bound, read_only, features가 알려줘요.
?project_ref=<ref>: 프로젝트 하나로 묶어요.ref를 비워도 이 프로젝트로 하고, 다른 ref는 거절해요.list_projects는 이 프로젝트만 보여 주고, 다른 프로젝트나 조직 전체에 닿는 도구(create_project, 팀, 알림 채널, 감사 로그, 결제)는 빠져요.?read_only=true: 아무것도 바꾸지 않는 도구만 있어요. 연결 전체가 읽기 토큰처럼 동작해요.?features=database,deploy: 고른 도구 그룹만 있어요(whoami,list_projects는 늘 있어요). 그룹: account, database, auth, storage, functions, deploy, domains, branching, logs, billing, ai, realtime, queues, gpu.?lang=ko|en|ja: 도구 설명과 오류의 언어. 아무것도 없으면 영어예요.
예: https://<주소>/mcp?lang=ko&project_ref=<ref>&read_only=true 는 그 프로젝트를 읽기만 하는 연결이에요. 사용자가 더 넓은 일을 원하면 옵션을 바꿔 다시 연결해 달라고 하세요.
순서를 틀리면 생기는 일
표를 만들고 규칙을 만들지 않으면 오류 없이 빈 배열이 돌아와요. 이 하나가 이 플랫폼에서 나오는 문제의 대부분이에요. blackwall://access-rules를 읽으세요.