AI 코딩 에이전트 시작하기

가장 빠르게 연결하는 방법은 PlaidCloud 안에서 직접 하는 것입니다. 헤더 도구 모음에서 밝은 테마/어두운 테마 전환 스위치 바로 왼쪽에 있는 AI 연결을 클릭하고, 사용하는 클라이언트를 선택한 다음, 표시되는 단계를 따르십시오. 워크스페이스의 MCP 서버 URL도 이미 입력되어 있습니다. 워크스페이스에서 AI 권한이 활성화되어 있으면 언제든지 사용할 수 있습니다. 이 페이지의 나머지 내용과 이어지는 클라이언트별 페이지는 계속 참조 문서로 활용할 수 있습니다. 웹 UI를 사용하지 않거나 인증 방식과 서버가 제공하는 기능을 전체적으로 파악하려면 계속 읽어 보십시오.

MCP 서버란?

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는 결과 집합을 가져오지 않고 크기만 확인합니다.

요청 일괄 처리

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

paginate_through_listing 레시피는 max_pages를 아무리 높게 전달해도 200페이지에서 멈추며, 일찍 멈추면 partial: true를 보고합니다. 이 제한과 max_items 제한 덕분에 단일 페이지 넘김 호출은 항상 종료됩니다.

레시피는 인식하지 못하는 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로 관리하십시오.

작업 시작 도우미

서버는 사람들이 이름을 대고 요청하는 작업을 위한 소규모 시작 도우미 세트를 제공합니다. 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 서버는 두 가지 인증 경로를 허용합니다.

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

정적 Bearer 토큰 받기

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의 사용자 지정 커넥터 연결.
문제 해결 — 일반적인 오류와 해결 방법.