콘텐츠로 이동

MCP로 연결된 AI 에이전트로 Data Foundation 다루기

MCP(Model Context Protocol)로 AI 에이전트를 워크스페이스에 연결하면, 에이전트는 이미 사용하고 있을 수도 있는 두 도구로 Data Foundation 프로젝트를 다룰 수 있습니다. project_describe는 프로젝트의 현재 상황을 읽고 수치를 설명하며, project_upsert는 프로젝트의 질문에 답합니다. PlaidCloud의 Weave AI 채팅도 같은 상태를 읽습니다. Weave AI 채팅: Data Foundation을 참조하십시오.

project_describe(project_id=..., include=['foundation'])는 프로젝트에 foundation 항목을 추가합니다. Data Foundation이 없는 프로젝트에서는 foundation이 null입니다.

필드 담고 있는 내용
run_state, warned 실행이 진행 중인지, 그리고 마지막 로드가 경고와 함께 끝났는지 여부입니다.
systems 프로젝트가 읽거나 지정한 각 시스템과 그 state(waiting_for_access, connected, loading, loaded 또는 failed), 로그인 방식, 마지막 로드 시각입니다. 액세스를 기다리는 시스템에 보낼 요청은 access_request에 있으며, GET /systems/access-request는 모든 시스템에 대한 요청을 하나로 제공합니다.
questions 답을 기다리는 질문 수와 그중 최대 50개로, 각 질문에는 id와 suggested 답이 있습니다.
upkeep 지금 누군가가 프로젝트에 해 주어야 할 일로, 각각 action이 있는 문장으로 표시됩니다. 대기 중인 질문, 액세스를 기다리거나 실패했거나 기한이 지난 시스템, 빨간색 보증 항목, 시스템이 변경한 마감된 월이 해당합니다. 마지막 로드가 묻지 않고 처리한 새 코드도 action 없이 나열합니다.
starter_questions 한 달 치 데이터가 로드된 뒤 프로젝트에 대해 물어볼 만한 질문입니다.
differences 각 시스템과 일치함 또는 그룹 합계가 일치함이 빨간색일 때, 각각의 최근 항목 최대 10개와 그 원인이 된 계정과 문서, 각 항목을 해소하는 방법과 담당자입니다.
group 그룹의 보고 통화와 회계연도가 시작되는 월입니다.
access_request 프로젝트가 지정한 각 시스템에 대해, 프로젝트가 읽는 데 필요한 액세스를 해당 시스템 관리자에게 요청하는 내용입니다.

프로젝트에 대한 읽기 전용 액세스만 있는 호출자에게는 questions가 null이며, 이때 upkeep에서도 질문이 제외됩니다. 프로젝트 설치가 아직 진행 중이면 foundation에는 설치 진행 상황(install), 프로젝트 링크, installing, 그리고 running인 run_state만 담깁니다. progress_id로 폴링하면 install.state가 done이 될 때까지 응답은 {project_id, install}뿐입니다(템플릿에서 프로젝트 만들기 참조).

같은 호출에 explain을 추가하면 재무제표의 한 줄을 설명합니다.

  • explain={'line': 'revenue', 'period': '2026-06'}는 explained를 반환합니다. 여기에는 해당 줄의 금액과 그 줄을 구성하는 줄, 엔터티, 계정이 담기며, 각 목록은 큰 순서대로 정렬되고 합계가 해당 줄과 일치합니다. 그 뒤에 있는 가장 큰 원장 문서 10개도 함께 담깁니다. 각 줄, 엔터티, 계정 구성 요소에는 해당 구성 요소만 설명하는 링크인 address가 있습니다. 내부 거래 제거 구성 요소와 Other lines (n), Other entities (n), Other accounts (n), Rounding 구성 요소에는 없습니다.
  • 해당 월까지의 회계연도 누계를 보려면 'span': 'ytd'를 추가합니다. total_assets와 같은 재무상태표 항목은 이를 무시하고 해당 월을 읽습니다. entity, account, source_system 및 재무제표의 다른 선택 항목으로 범위를 좁힙니다.
  • 해당 월 이후 그 줄이 왜 변동했는지 보려면 'against': '2026-05'를 추가합니다. 그러면 각 구성 요소에 amount, before, change가 표시되며, 변동이 큰 순서대로 정렬됩니다.
  • explain={'commentary': '2026-06'}는 월말 코멘터리 초안인 commentary를 반환합니다. 해당 월과 그 월까지의 회계연도 누계에 대한 매출, 매출총이익, EBITDA, 당기순이익을 예산 및 전년 동월과 비교합니다. 최근 월을 보려면 월로 null을 지정합니다. 이는 항상 초안이므로 사용하기 전에 확인하십시오.

line은 revenue, gross_margin, ebitda, operating_profit, net_income, total_assets 같은 재무제표의 줄 키입니다. 재무제표에 없는 줄, YYYY-MM 형식이 아닌 월, explain이 받지 않는 키는 해당 항목을 명시한 메시지와 함께 거부됩니다. 모든 수치는 호출자의 행 액세스를 따릅니다.

project_upsert(project_id=..., spec={}, answers=[{'id': ..., 'value': ...}])는 questions의 id를 사용하여 프로젝트의 질문에 답합니다. 직접 답하지 않은 질문에 대해 제안된 답을 모두 수락하려면 accept_all_suggested=True를 추가합니다. 답을 하려면 프로젝트에 대한 편집 액세스가 필요하며, 답은 다음 로드 또는 변경 사항 적용 때 적용되고 프로젝트 기록에 남습니다.

먼저 전체 배치를 검사합니다. 답 하나라도 유효하지 않으면 아무것도 기록하지 않습니다. dry_run=True는 검사하거나 기록하지 않고 answers에 제공한 답의 수를 세며, 제안된 답도 모두 받아들여지는지 알려 줍니다. 답은 기존 프로젝트에만 적용됩니다. 답을 제공할 때는 spec이 비어 있어야 하며 template은 생략해야 합니다.

project_upsert(spec={'name': ...}, template=...)는 Data Foundation 템플릿을 새 비공개 프로젝트로 백그라운드에서 설치합니다. spec에 memo와 lakehouse_id를 지정하면 이를 사용합니다. 반환된 progress_id로 project_describe(include=['foundation'], progress_id=...)를 폴링하십시오. install.state가 done이 될 때까지 응답은 {project_id, install}뿐입니다. 프로젝트가 시스템을 지정하면 foundation.access_request에 각 시스템 관리자에게 보낼 요청이 담깁니다.

같은 프로젝트는 REST API의 /rest/v1/analyze/foundation/{project_id} 아래에서도 사용할 수 있습니다. 읽으려면 analyze.project.read 역할이, 변경하려면 analyze.project.write 역할이 필요합니다. GET /questions에는 프로젝트에 대한 편집 액세스도 필요하며, 읽기 전용 액세스만 있는 호출자는 거부됩니다.

엔드포인트 하는 일
GET /systems 프로젝트가 읽거나 지정한 시스템과 각 시스템의 상태입니다.
POST /systems 시스템을 지정합니다({"systems": [{"type": ..., "connection_id": ...}]}). 자격 증명이나 온프레미스 에이전트로 로그인하는 연결이 지정된 시스템은 즉시 연결되고 로드됩니다. 동의 방식으로 로그인하고 연결이 없는 시스템에는 연결이 새로 만들어지며, 그 행에 authorize_url이 담깁니다. 누군가 이 URL에서 시스템 자체의 로그인 화면으로 액세스를 승인하므로 PlaidCloud에 암호가 전송되지 않습니다.
POST /systems/attach 승인이 끝나면 방금 승인된 각 동의 방식 시스템을 연결하고 로드합니다. 아직 연결할 수 없는 시스템은 대기 상태로 남으며, 그 행에 이유가 표시됩니다.
DELETE /systems/{key} 시스템을 제외합니다. 아직 대기 중인 시스템은 제거하고 그 시스템을 위해 만든 연결을 삭제하며, 연결된 시스템은 연결을 해제합니다.
GET /systems/access-request 프로젝트의 모든 시스템에 필요한 액세스를 요청하는 하나의 요청입니다.
POST /load 로드를 시작하거나, 쿼리 매개변수 pull=false를 지정하면 변경 사항 적용을 시작합니다. GET /systems의 키를 사용하여 {"system": ...}을 지정하면 해당 시스템만 읽습니다. 모델은 여전히 모든 시스템의 행을 기준으로 최신 상태로 갱신됩니다.
GET /questions 답을 기다리는 질문을 그룹별로 반환하며, 각 질문에는 제안된 답과 그 근거가 담깁니다.
POST /questions/answers 답을 제공하거나({"answers": [{"id": ..., "value": ...}]}), 제안된 답을 모두 수락합니다("accept_all_suggested": true).
GET /summary 요약 페이지입니다. 프로젝트의 현재 상황, 다섯 가지 보증 항목, 각 시스템의 데이터가 얼마나 최신인지, 마감된 월, 시작 질문이 담깁니다.
POST /close 모든 엔터티 또는 지정한 엔터티를 특정 월까지 마감합니다({"through": "2026-06", "entities": []}).
POST /close/accept-change 시스템이 변경한 마감된 월에 대해 시스템이 현재 보유한 내용을 받아들입니다({"system": ..., "entity": ..., "period": ...}).
GET /history 누가 무엇을 답하고, 일치시키고, 마감하고, 재작성하고, 변경했는지를 최신 순으로 한 페이지에 200개씩 반환합니다. 다음 페이지를 보려면 next_cursor를 cursor로 전달합니다. GET /history.xlsx는 전체를 내려받습니다.
GET /reports 프로젝트의 대시보드와 각 대시보드의 링크입니다.
GET /explain 재무제표의 한 줄을 구성하는 내용으로, line, period 및 위의 선택 항목을 쿼리 매개변수로 지정합니다. GET /explain.xlsx는 그 뒤에 있는 모든 원장 문서를 내려받습니다. Enterprise Profitability 프로젝트에서 cogs, opex, operating_margin은 한 엔터티에 대한 모델의 계층으로 설명됩니다.

연결로 시스템을 지정하려면 해당 연결에 대한 액세스가 필요하며, 시스템을 위한 연결을 만들거나 승인 후 시스템을 연결하려면 analyze.connection.write 역할이 필요합니다. 질문에 답하거나, 시스템을 지정하거나 제거하거나, 월을 마감하려면 프로젝트에 대한 편집 액세스가 필요합니다. 월을 마감하거나 마감된 월의 변경을 받아들이려면 프로젝트의 관리자 또는 아키텍트여야 합니다. 실행이 프로젝트를 점유하고 있는 동안 로드, 시스템 제거, 월 마감 또는 변경 수락을 시도하면 409 및 run_locked와 함께 거부됩니다.