MCP로 연결하기

D2B의 MCP 서버는 https://d2b.dev/mcp/(Streamable HTTP)입니다. 인증은 두 가지입니다. 호스트의 로그인(OAuth 2.1. 브라우저에서 승인하면 호스트가 1시간짜리 토큰을 스스로 갱신) 또는 PAT Bearer 헤더. 도구는 REST / CLI / SDK와 같은 표면이며, 타입 스키마가 붙은 툴 호출로 사용할 수 있습니다(호스트의 도구 목록이 항상 최신입니다).

규범은 서버가 전달합니다

연결하면 초기화 응답의 instructions에 운용 규범(어떤 도구를 언제, 파일은 참조로 반입, 파생은 transform으로, 409는 다시 읽기, 구간마다 commit_snapshot, 정리는 delete_workbook …)이 담깁니다. 호스트가 instructions를 잘라내면 같은 문장을 d2b://guide 리소스로 읽을 수 있습니다. 리포지토리에는 연결과 경로 선택만 있으면 됩니다(코딩 에이전트에서 D2B 사용하기).

워크스페이스 프로비저닝도 MCP로 할 수 있습니다(provision_workspace / delete_workspace. workspaces:create / workspaces:delete 스코프를 가진 계정 전체 키가 필요하며, 워크스페이스에 고정된 키는 형제 워크스페이스를 만들 수 없습니다).

로그인(OAuth)

URL만 등록하면 호스트가 https://d2b.dev/mcp/의 401에서 인가 서버를 찾아 브라우저로 D2B 동의 화면을 엽니다. 화면에는 앱 이름, 돌아갈 호스트, 부여되는 권한(workbooks의 read / write / delete와 cloud-files:read), 그리고 어느 계정으로 동작할지(기본 계정 또는 개발자 계정 중 하나)가 표시되며 이를 확인하고 승인합니다. 액세스 토큰은 1시간 유효하고 호스트가 리프레시 토큰으로 갱신합니다. 콘솔의 설정 > 토큰에 oauth:<앱 이름>으로 표시되므로 연결 단위로 언제든 폐기할 수 있습니다.

앱 이름은 호스트가 스스로 밝힌 것이며 D2B는 검증하지 않습니다. 예상하지 못한 동의 화면은 거부하세요. OAuth를 지원하지 않는 호스트나 CI 같은 무인 환경에서는 기존처럼 PAT Bearer 헤더를 사용합니다.

호스트별 설정

claude mcp add d2b --transport http https://d2b.dev/mcp/

헤더 없이 등록하면 첫 사용 시 로그인을 요구합니다. 무인 환경에서는 PAT를 전달합니다:

claude mcp add d2b --transport http https://d2b.dev/mcp/ \
  --header "Authorization: Bearer $D2B_PAT"

~/.cursor/mcp.json(또는 프로젝트의 .cursor/mcp.json). URL만 적으면 Cursor가 로그인을 안내합니다. PAT로 고정하려면 headers를 추가합니다:

{
  "mcpServers": {
    "d2b": {
      "url": "https://d2b.dev/mcp/",
      "headers": { "Authorization": "Bearer d2b_pat_..." }
    }
  }
}

.vscode/mcp.json. URL만으로 VS Code가 로그인을 안내합니다(PAT는 headers 추가):

{
  "servers": {
    "d2b": {
      "type": "http",
      "url": "https://d2b.dev/mcp/",
      "headers": { "Authorization": "Bearer ${input:d2b_pat}" }
    }
  },
  "inputs": [{ "id": "d2b_pat", "type": "promptString", "password": true, "description": "D2B PAT" }]
}

Settings → Connectors → Add custom connector에 https://d2b.dev/mcp/를 등록합니다. 인증은 기본값인 “지금 로그인” 그대로 두면 됩니다(브라우저에서 D2B 동의 화면이 열립니다). PAT로 연결하려면 “로그인 없음”을 고르고 요청 헤더에 Authorization: Bearer d2b_pat_...를 설정합니다. 둘 다 없는 버전에서는 mcp-remote를 거칩니다:

{
  "mcpServers": {
    "d2b": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://d2b.dev/mcp/",
               "--header", "Authorization: Bearer d2b_pat_..."]
    }
  }
}

PAT를 쓴다면 workbook 범위 + 속도 제한의 최소 권한 토큰을 권장합니다(빠른 시작 §1).

도구 지도

목적	도구
발견	`list_my_data` / `get_schema`(`include_json_schema`) / `profile_table` / `get_lineage` / `get_downstream` / `search`
읽기	`read_table` / `query_sql` / `validate_sql`
검증	`review_table` / `review_workbook` (근거가 있는 지적: 원본 파일의 수식, 표의 불변 조건, 라벨과 정의의 일치. `mode="agent"`는 작업을 반환하므로 `get_job`으로 기다림)
데이터 반입(참조 우선)	`ingest_url` / `request_upload` → `ingest_upload` / `list_cloud_files` → `import_cloud_file` / `track_onedrive_file` / `ingest_file`
구조 확인 / 원본을 따르는 revise	`analyze_source` / `get_parse_spec` / `update_parse_spec` / `materialize_source` / `revise_source`
컨테이너(워크북·워크스페이스)	`list_my_workspaces` / `create_workbook` / `delete_workbook` / `provision_workspace` / `delete_workspace`
만들기·고치기	`create_table` / `add_transform` / `list_transforms` / `upsert_rows` / `delete_rows` / `write_a1` / `put_sheet` / `get_sheet` / `list_sheets`
스키마	`add_column` / `rename_column` / `retype_column` / `drop_column` / `rename_table`
수식·설명	`set_formula_column` / `list_formula_columns` / `clear_formula_column` / `set_artifact_description` / `set_column_description` / `set_table_style` / `get_table_style`
이력	`list_snapshots` / `commit_snapshot` / `restore_snapshot` / `diff_snapshots` / `recompute_stale` / `list_ops` / `undo_op`
충돌·동기화·납품	`list_conflicts` / `resolve_conflict` / `export_tables` / `bind_external_sheet` / `list_sync_bindings` / `unbind_external_sheet` / `list_file_links` / `sync_file_link`

타입

도구 입력은 엄격하게 타입이 지정됩니다(enum / 구조화 모델. 하네스가 생성 시점에 잘못된 값을 걸러낼 수 있습니다). 유일하게 데이터에 의존하는 upsert_rows.rows는 get_schema(name, include_json_schema=true)가 반환하는 행 단위 JSON Schema로 실행 시 제약할 수 있습니다.

오류는 REST와 같은 problem+json 어휘(suggested_fix 포함)로 반환됩니다 — 오류 읽는 법.

전송은 무상태 streamable HTTP입니다 — 서버에 대화 세션을 유지하지 않고 각 요청이 자체 완결적입니다(재시도·수평 확장에 안전).