콘텐츠로 이동

AI 코딩 에이전트 시작하기

연결하는 가장 빠른 방법은 PlaidCloud 안에서 아바타(사용자) 메뉴를 열고 AI 연결을 선택하는 것입니다. 사용하는 클라이언트를 선택하고 표시되는 단계(워크스페이스의 MCP 서버 URL이 이미 채워져 있음)를 따르십시오. 워크스페이스에서 AI 사용 권한이 활성화되어 있으면 언제든지 사용할 수 있습니다. 이 페이지의 나머지 부분과 뒤따르는 클라이언트별 페이지는 계속 참고 자료로 제공됩니다. 웹 UI를 사용하지 않거나, 인증과 서버가 제공하는 기능을 전체적으로 파악하려면 계속 읽으십시오.

Model Context Protocol은 AI 에이전트가 외부 도구 및 데이터와 통신하도록 하는 개방형 표준입니다. PlaidCloud는 모든 워크스페이스에서 REST API가 사용하는 것과 같은 핵심 헬퍼를 감싸는 MCP 서버를 실행합니다. 의도별(find, describe, upsert, run, organize)로 그룹화되어 있으므로 에이전트가 1,000개 이상의 저수준 RPC 메서드 이름을 로드하지 않고도 인터페이스를 탐색할 수 있습니다.

서버 주소는 다음과 같습니다.

https://<your-workspace>.plaid.cloud/mcp

<your-workspace>를 워크스페이스 서브도메인(PlaidCloud UI에 로그인할 때 사용하는 주소)으로 바꾸십시오.

카탈로그는 에이전트에 필요한 일상적인 기능 대부분을 다룹니다.

  • 프로젝트, 워크플로, 단계 — 단계 수준 다시 실행과 버전 기록을 포함한 find/describe/upsert/run/organize.
  • 테이블, 뷰, 쿼리 — 스키마 검사, 쿼리 실행, 내보내기, 스냅샷, 브랜치. 뷰는 테이블 탐색기에서 만들었든 워크플로가 만들었든 PlaidCloud에서 보는 것과 같은 뷰입니다.
  • 차원 — describe, find, upsert, 버전 관리, 노드/별칭/속성 관리.
  • 연결 — 외부 시스템에 대한 연결 find/upsert/test.
  • Lakehouse — 브랜치, 스냅샷, optimize/vacuum 작업.
  • ID — 멤버, 그룹, 세션, 배포 목록.
  • 문서, 대시보드, UDF, 편집기, 에이전트, 게시 — 도메인별 도구.
  • 워크플로 마이그레이션 — Document에 준비된 Alteryx(alteryx_convert), KNIME(knime_convert), Prophecy(prophecy_convert), Savant(savant_convert) 내보내기를 PlaidCloud 워크플로로 변환하고 포트폴리오 마이그레이션 작업을 조율합니다.
  • PlaidCloud 문서 — docs_search는 키워드로 PlaidCloud 문서의 페이지를 찾고 docs_fetch는 페이지 전체를 읽으므로, 에이전트가 기능으로 빌드하기 전에 작동 방식을 확인할 수 있습니다.
  • 워크플로 로그 및 실행 추적 — workflow_logs, workflow_run_status, workflow_job_track.

모든 도구는 균일한 엔벨로프 {ok, data, next_cursor?, total?}를 반환하며, 실패는 {ok: false, error: {code, retryable, message, hint?}}를 사용합니다. 변경 작업은 dry_run=True를 지원하여 쓰기 없이 계획만 검증할 수 있습니다.

도구 결과는 에이전트 컨텍스트에서 가장 큰 비중을 차지하므로, find 및 describe 도구는 기본적으로 적당한 분량만 반환하며 필요하면 늘릴 수 있습니다.

  • 행. find는 페이지당 25건의 일치 항목을 반환합니다(step_find는 50건). 제한된 페이지는 next_cursor를 설정하며, find 도구는 추가로 잘린 목록을 truncated에 표시합니다. 둘 중 하나라도 있으면 “이것이 전부”가 아니라 “더 있다”는 뜻입니다. total은 항상 전체 개수를 보고합니다. limit를 높이거나 커서로 페이지를 넘기십시오.
  • 열. fields=['id', 'name', 'update_time']를 전달하면 해당 열만 반환됩니다. 어떤 레코드에도 나타나지 않는 필드 이름은 조용히 누락되지 않고 사용 가능한 필드를 나열하는 오류가 되므로, 오타가 있으면 요청한 것보다 적게 조용히 반환하지 않고 분명하게 실패합니다. 선별된 집합을 제공하는 도구는 field_set='minimal' | 'default' | 'full'도 사용할 수 있습니다. 특정 도구가 허용하는 매개변수는 mcp_introspect를 호출하여 확인하십시오.
  • 개수. count_only=True는 결과 집합을 가져오지 않고 크기만 알려 줍니다.

project_upsert나 workflow_upsert의 것처럼 도구가 받는 spec은 나열된 필드만 허용합니다. 인식하지 못하는 필드는 무시되어 나중에 아무 효과가 없었음을 알게 되는 대신, 필드 이름을 알려 주는 오류와 함께 거부됩니다. 이름을 수정하고 요청을 다시 보내십시오. workflow_upsert는 워크플로 설명을 memo로 받으며 description도 같은 의미의 다른 이름으로 허용합니다.

mcp_batch는 여러 도구 호출을 하나의 요청으로 묶습니다. 최대 100개의 호출을 받고, 제한된 수만큼 동시에 실행하며, 다른 mcp_batch나 레시피 안에 중첩할 수 없습니다. 대신 호출을 하나의 평면 배치에 나열하면 되며, 전송 비용은 더 들지 않습니다. 한도를 초과한 배치는 조용히 잘리지 않고 해당 한도를 알려 주는 메시지와 함께 거부됩니다. 이 한도는 하나의 요청이 시작할 수 있는 작업을 제한할 뿐 전체 작업량을 제한하지 않으므로, 더 큰 작업은 여러 배치로 나누십시오.

paginate_through_listing 레시피는 max_pages를 아무리 높게 전달해도 200페이지 후에 중지하며, 일찍 중지하면 partial: true를 보고합니다. 이 한도와 max_items 한도 덕분에 하나의 paginate 호출은 항상 종료됩니다.

레시피는 인식하지 못하는 params 키를 거부하며, 메시지에는 해당 레시피가 허용하는 키가 나열됩니다. 따라서 선택적 매개변수의 철자가 틀리면 무시되어 호출이 요청과 다른 질문에 조용히 답하는 대신 분명하게 실패합니다. 특정 레시피가 받는 키는 mcp_recipes(name=...)를 호출하여 확인하십시오.

모든 행이 같은 필드를 가진 큰 결과는 객체 목록이 아니라 열 지향으로 반환되므로, 필드 이름이 행마다 한 번이 아니라 한 번만 전송됩니다.

{"_fmt": "cols", "cols": ["id", "name"], "rows": [["a1", "Sales"], ["b2", "Costs"]]}

i번째 행은 dict(zip(cols, rows[i]))입니다. 작은 결과와, 행들의 필드 집합이 동일하지 않은 결과는 일반 객체 배열로 유지되므로 두 가지 형태가 모두 나타나며, 이러한 응답을 직접 읽는 코드는 각각을 처리해야 합니다. 이를 감싸는 엔벨로프는 변하지 않으며, 어떤 값도 변환되거나 반올림되지 않습니다. 에이전트는 연결할 때 이 형태에 대해 안내받으며 사용자가 따로 안내하지 않아도 읽을 수 있습니다. 일반적인 목록 트래픽에서 문자 수의 약 30%, 에이전트 읽기 예산의 약 15%가 절약되므로 실제 질문에 사용할 컨텍스트가 남습니다. (반복되는 필드 이름은 모델이 읽기에 부담이 적으므로 두 수치가 다르며, 문자 절감 폭이 항상 더 큽니다.)

실시간 카탈로그를 확인하려면 에이전트를 서버에 연결하고 mcp_introspect를 인수 없이 호출하십시오. 현재 도구 수, 도메인별 요약, 매개변수 시그니처가 반환됩니다. 여러 도구를 조합하는 일반적인 플레이북(큰 목록 페이지네이션, 스냅샷 후 수정, 실패한 단계 다시 실행 등)은 mcp_recipes를 사용하십시오.

테이블, 워크플로, 단계, 프로젝트, 차원, 뷰, 편집기, UDF, 연결, 웨어하우스의 레이블을 설정하는 모든 upsert 도구는 두 개의 매개변수를 받습니다. labels는 레이블을 추가하고 remove_labels는 제거합니다. 개체의 다른 레이블은 그대로 유지됩니다. 제거가 추가보다 먼저 적용되므로 호출 한 번으로 레이블 이름을 바꿀 수 있습니다.

{"remove_labels": ["01"], "labels": ["001"]}

개체에 없는 레이블을 제거해도 아무 일도 일어나지 않습니다.

뷰 도구는 PlaidCloud에서 보는 뷰와 함께 작동합니다.

  • view_find는 뷰를 나열하고 view_describe는 ID 또는 이름으로 뷰 하나를 반환합니다.
  • view_upsert는 뷰를 만들거나 제자리에서 업데이트합니다. 업데이트해도 뷰의 ID와 레이블이 유지되며, 쿼리를 다시 보내지 않고 레이블만 변경할 수 있습니다.
  • view_organize는 뷰를 삭제, 이름 변경, 복제, 이동합니다.
  • 쿼리 매개변수는 %(name)s 자리 표시자로 작성합니다.

뷰는 테이블 폴더 트리를 공유하므로 폴더를 관리하려면 table_organize를 사용하십시오.

네이티브 단계로 워크플로 구성하기

섹션 제목: “네이티브 단계로 워크플로 구성하기”

데이터가 PlaidCloud에 들어오면 에이전트는 SQL 추출 단계 대신 네이티브 테이블 단계, 즉 Table Extract, 조인 단계, Table Melt, Table Union All, Table Lookup 단계로 각 변환을 구성하도록 안내받습니다. 네이티브 단계는 필터와 식의 변수를 값으로 채우며, PlaidCloud는 프로젝트의 웨어하우스에 맞게 해당 SQL을 생성합니다. SQL 추출 단계는 쿼리를 작성된 그대로 웨어하우스에 보내며, 변수를 채우지 않고 SQL은 하나의 웨어하우스용으로 작성됩니다.

에이전트는 query_run(mode='config')로 Table Extract 설정을 시험해 보고 단계를 저장하기 전에 행을 확인할 수 있습니다. 이 설정은 step_upsert로 저장할 설정과 같습니다. SQL 추출 단계를 저장하면 step_upsert가 대신 사용할 네이티브 단계를 알려 주는 prefer_native_steps 항목을 config_warnings에 반환하며, describe_step_operation에도 같은 안내가 담겨 있습니다. SQL 추출은 어떤 네이티브 단계로도 표현할 수 없는 작업에 계속 사용할 수 있습니다.

서버는 사람들이 이름으로 요청하는 작업을 위한 소수의 시작 도우미를 제공합니다. MCP 프롬프트를 지원하는 클라이언트는 이를 나열하고 메뉴로 제공합니다(위치는 클라이언트 문서를 확인하십시오). 따라서 도구 호출 순서를 설명하지 않고 작업을 선택하기만 하면 됩니다.

시작 도우미 제공할 내용
CSV 파일을 테이블로 가져오기 파일, 그리고 선택 사항으로 프로젝트, 파일이 있는 폴더, 새 테이블의 이름
비용 변동 설명 결과 테이블, 그리고 선택 사항으로 프로젝트와 두 기간
실패한 워크플로 디버그 워크플로, 그리고 선택 사항으로 프로젝트
프로젝트 데이터 탐색 찾으려는 내용, 그리고 선택 사항으로 프로젝트

각 도우미는 명령이 아니라 시작 메시지입니다. 에이전트가 이를 읽고 직접 도구를 구동하므로 메시지를 편집하거나 거기서부터 대화를 이어갈 수 있습니다.

개체 모델을 몰라도 파일 가져오기

섹션 제목: “개체 모델을 몰라도 파일 가져오기”

가져오기 시작 도우미는 가장 많은 작업을 줄여 줍니다. 단순한 방법은 문서 계정 찾기, 파일로 이동, 대상 테이블 만들기, 가져오기 실행의 네 가지 도구를 올바른 순서로 사용해야 하며, 어느 하나라도 잘못 추측하면 몇 번의 호출 뒤에 흐름이 끝나기 때문입니다.

구분자로 구분된 텍스트(CSV, TSV 등)를 읽습니다. Excel 통합 문서나 Parquet 파일은 잘못 읽는 대신 거부되므로, 이러한 파일은 워크플로에서 해당하는 가져오기 단계로 가져오십시오.

대신 bulk_import_csv 플레이북은 계정을 이름으로, 파일을 이름 또는 경로로 받습니다.

mcp_recipe_run(name='bulk_import_csv', params={
'project_id': '<project>',
'document_path': 'sales_2026.csv',
'document_account': 'Demo Data',
})

계정을 식별자로 확인하고, 파일을 찾고, 파일 자체에서 읽은 열과 유형으로 테이블을 만든 다음 로드합니다. 따라서 계정 ID나 열 사양을 제공할 필요가 없습니다. table_name의 기본값은 확장자를 뺀 파일 이름이고 table_path의 기본값은 프로젝트 루트입니다.

폴더를 알고 있으면 'document_path': 'raw/sales_2026.csv'처럼 지정하십시오. 그러면 검색이 해당 폴더로 한정됩니다. 폴더에 지정한 파일은 해당 폴더에서만 일치하며, 더 아래에 있는 같은 이름의 파일은 대신 가져오지 않고 선택지로 제안됩니다.

인수가 모호하면 추측하지 않고 결과에서 질문합니다.

{
"needs_choice": "document_account",
"question": "More than one document account is named 'Archive'. Which one?",
"candidates": [{"id": "...", "name": "Archive"}, {"id": "...", "name": "Archive"}]
}

후보를 도움을 받는 사람에게 보여 준 다음, 후보를 받은 그대로 전달하면서 그 사람의 답으로 플레이북을 다시 호출하십시오. 파일을 찾을 수 없으면 응답에 가장 비슷한 이름이 나열되고 검색한 파일 수가 보고되므로, “없음”과 “내가 찾은 곳에 없음”을 구별할 수 있습니다.

PlaidCloud의 MCP 서버는 두 가지 인증 경로를 지원합니다.

  1. 동적 클라이언트 등록(DCR)을 통한 OAuth 2.1 + PKCE. Claude.ai의 사용자 지정 커넥터 UI가 사용하는 방식이며 Claude Code의 MCP 브리지에서도 기본값입니다. 클라이언트가 스스로 등록하고 PlaidCloud의 Keycloak 로그인으로 리디렉션합니다. 로그인하면 PlaidCloud가 애플리케이션 이름과 자격 증명을 보낼 리디렉션 URI를 표시하는 Application Access Request 페이지를 보여 줍니다. 인증당 한 번 승인하여 토큰을 받으십시오. 이는 형식적인 절차가 아니라 보안 통제입니다. 애플리케이션 이름과 리디렉션 URI가 실제로 연결하려는 클라이언트와 일치하는지 확인하고, 직접 시작하지 않은 요청은 승인하지 마십시오.
  2. Authorization 헤더의 정적 전달자 토큰. 사용할 수 있는 브라우저 리디렉션이 없거나 구성 파일에 장기 토큰을 두려는 에이전트 런타임용입니다. PlaidCloud는 토큰을 대신 발급하는 헬퍼 페이지를 제공합니다(아래 참조).

PlaidCloud에 이미 로그인한 브라우저 탭에서 다음 URL을 여십시오.

https://<your-workspace>.plaid.cloud/mcp/setup/token

이 페이지는 에이전트의 MCP 구성에 바로 붙여 넣을 수 있는 JSON 스니펫을 반환합니다. 스니펫은 워크스페이스마다 다릅니다.

토큰의 수명은 Keycloak 영역의 액세스 토큰 수명 정책(보통 몇 시간에서 하루)에 따라 결정됩니다. 갱신하려면 같은 URL을 다시 로드하십시오. 브라우저 세션이 토큰을 자동으로 다시 발급합니다.

이 섹션의 나머지 부분에서는 특정 AI 에이전트 클라이언트의 설정을 안내합니다.

  • Claude Code — Anthropic의 코딩 에이전트(CLI, VSCode 확장, JetBrains 플러그인).
  • Claude Desktop 및 Claude.ai — “사용자 지정 커넥터”를 사용하는 소비자용 Claude 앱(데스크톱)과 웹(claude.ai).
  • Cursor — AI 네이티브 코드 편집기.
  • GitHub Copilot — VSCode의 Copilot 에이전트 모드.
  • Google Gemini CLI — gemini-cli 및 Gemini Code Assist.
  • ChatGPT — 현재 지원 상태와 권장 해결 방법.
  • Grok — Grok의 사용자 지정 커넥터 연결.
  • 문제 해결 — 일반적인 오류와 해결 방법.