# 처음부터 끝까지

이 서버로 할 수 있는 일의 순서예요. 각 단계에 쓰는 도구를 함께 적었어요.

## 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를 읽으세요.

---

https://end.blackall.ai/docs/start?lang=ko