문제 해결

Cursor(또는 다른 엄격한 클라이언트)가 전혀 연결되지 않음

증상: 같은 워크스페이스가 Claude Code에서는 작동하는데, Cursor와 같은 엄격한 클라이언트에서는 서버가 세션을 설정하지 못합니다.

원인: 서버 URL 끝에 슬래시가 붙어 있습니다. .../mcp/가 아니라 https://<your-workspace>.plaid.cloud/mcp를 사용하십시오. 엄격한 클라이언트는 끝에 슬래시가 있는 URL을 거부하거나(또는 이전 경로가 보내던 리디렉션을 따르지 않으며), Claude Code 같은 관대한 클라이언트는 이를 허용합니다.

해결: 구성의 url에서 끝의 슬래시를 제거하고 다시 연결하십시오. 이 가이드의 모든 예시는 슬래시가 없는 형식을 사용합니다.

“failed to Connect” / “session Not Found”

증상: 클라이언트 구성은 올바른 것 같은데 클라이언트의 MCP 상태 패널에서 서버가 실패로 표시됩니다. 서버 로그에 404 Session not found 오류가 나타납니다.

원인: 일부 MCP 클라이언트(특히 정적 Authorization 헤더를 사용하는 Claude Code 2.1.111)에 있는 알려진 버그로, 클라이언트가 연속된 HTTP 요청 사이에 mcp-session-id를 유지하지 않습니다. PlaidCloud의 MCP 서버는 이를 피하기 위해 상태 비저장 HTTP 모드로 실행됩니다. 수정 이후 다시 배포되지 않은 테넌트에서 이 증상이 나타난다면 관리자에게 재배포를 요청하십시오.

재배포가 완료되기 전에는 클라이언트에서 다른 코드 경로를 사용하므로 (정적 Authorization 헤더를 쓰지 않는) OAuth 흐름은 계속 작동합니다.

“application Access Request” 페이지

증상: OAuth 인증 중에 PlaidCloud에 로그인한 뒤 애플리케이션과 리디렉션 URI가 표시된 Application Access Request 페이지로 이동하며, 흐름을 계속하려면 승인을 클릭해야 합니다.

원인: 정상적인 동작입니다. PlaidCloud의 MCP 서버를 통한 모든 OAuth 인증에서 이 페이지가 표시되므로, 토큰이 발급되기 전에 연결하려는 대상을 확인할 수 있습니다. 이 페이지에는 요청한 애플리케이션과 자격 증명을 보낼 리디렉션 URI가 표시됩니다. 둘 다 실제로 연결하려는 클라이언트와 일치하는지 확인하고, 직접 시작하지 않은 요청은 승인하지 마십시오.

이미 연결된 클라이언트는 토큰을 갱신할 때 이 페이지를 다시 보지 않으며, 새로 인증하는 경우(첫 연결이거나 갱신 토큰이 만료되었거나 취소된 후)에만 다시 표시됩니다.

해결: 해결할 것은 없으며 페이지를 승인하고 계속 진행하십시오. 한 브라우저(또는 프로필)에서 인증을 시작했는데 페이지가 다른 브라우저에 표시되면 완료되지 않습니다. 동의는 흐름을 시작한 브라우저에 연결되어 있기 때문입니다. PlaidCloud에 로그인한 같은 브라우저에서 인증을 다시 시작하십시오.

Claude Code 로그인 중 “oauth Flow is Not in Progress”

증상: 브라우저에서 인증하고 콜백 URL을 Claude Code에 붙여 넣었는데, 진행 중인 흐름이 없다는 메시지가 표시됩니다.

원인: 브리지의 메모리 내 OAuth 상태는 포트별로 유지되며, authenticate와 complete_authentication 도구 호출 사이에 손실될 수 있습니다. 특히 브라우저 콜백이 localhost에 도달할 수 없는 원격/SSH 세션에서 그렇습니다.

해결: 정적 Bearer 흐름으로 전환하십시오. PlaidCloud에 로그인한 브라우저에서 https://<your-workspace>.plaid.cloud/mcp/setup/token을 열고, 스니펫을 .mcp.json에 복사한 다음 Claude Code를 다시 시작하십시오.

토큰 만료

증상: 어제까지 작동하던 도구가 이제 401 Unauthorized를 반환합니다.

원인: 정적 Bearer 토큰은 Keycloak 렐름의 액세스 토큰 수명 정책(보통 몇 시간에서 하루)을 따릅니다.

해결: https://<your-workspace>.plaid.cloud/mcp/setup/token을 다시 불러와 새 토큰을 발급받고 구성에 붙여 넣으십시오. 오래 유지되는 세션에는 OAuth를 권장합니다. OAuth를 지원하는 클라이언트는 토큰을 자동으로 갱신합니다.

“no access_token in Session”

증상: PlaidCloud에 로그인되어 있는데도 /mcp/setup/token을 열면 “Sign-in required” 또는 “No access_token in session”이 표시됩니다.

원인: Keycloak 토큰을 캐시하지 않는 로그인 경로로 세션이 설정되었습니다(드물지만 가능합니다).

해결: PlaidCloud에서 로그아웃한 뒤 표준 로그인 페이지로 다시 로그인하십시오. 새 세션에는 액세스 토큰이 포함됩니다.

도구가 없거나 카탈로그가 불완전함

증상: mcp_introspect가 예상보다 적은 도구를 반환하거나, 필요한 특정 도구가 없습니다.

원인 1 — 스코프: 도구는 특정 PlaidCloud 스코프(예: analyze.workflow.write)를 요구합니다. 계정에 해당 스코프가 없으면 도구가 실행을 거부합니다. mcp_introspect(name='<tool>')를 실행하여 required_scopes를 확인하십시오. 워크스페이스 관리자에게 스코프 부여를 요청하거나, 해당 스코프가 있는 계정으로 작업을 실행하십시오.

원인 2 — 버전 불일치: 이전 배포에는 최신 문서에 설명된 도구가 모두 없을 수 있습니다. mcp_introspect()의 도구 개수를 현재 버전의 릴리스 노트와 비교하고, 필요하면 재배포를 요청하십시오.

멀티 테넌트: 에이전트가 방금 어느 테넌트에 접근했나요?

증상: PlaidCloud 테넌트를 여러 개 구성해 두었는데 에이전트의 응답이 어느 테넌트에서 온 것인지 알 수 없습니다.

해결: 프롬프트에 테넌트를 명시하십시오(“dev 테넌트에서 워크플로를 나열해 줘…”). 구성에서 정한 MCP 서버 이름(예: plaidcloud-prod, plaidcloud-dev)은 모델이 구분하는 식별자로도 쓰입니다. 위험도가 높은 작업을 할 때는 실제로 필요해질 때까지 커넥터 선택기에서 운영 환경을 꺼 두십시오.

속도 제한과 할당량

PlaidCloud의 REST 인터페이스는 UI 앞단에 있는 것과 같은 미들웨어를 통해 분당 요청 수 기준으로 속도가 제한됩니다. MCP 호출도 이 제한을 공유합니다. 에이전트가 find 호출을 길게 연속해서 보내면(예: 모든 프로젝트, 워크플로, 단계를 열거하려는 경우) 제한에 걸릴 수 있습니다. 전체 결과 집합을 가져오는 대신 페이지 나누기(cursor, limit)와 크기 확인용 count_only=True를 사용하십시오.

find는 기본적으로 페이지당 25개 행을 반환하며(step_find는 50개), 따라서 큰 집합을 열거하려면 예전보다 호출이 더 많이 필요합니다. 의도적으로 전체를 훑을 때는 기본값으로 페이지를 넘기지 말고 limit을 높이십시오. 반대로 제한에 계속 걸린다면, count_only=True와 더 좁은 fields=[...] 지정만으로도 전체를 훑을 필요가 없었을 가능성이 큽니다.

목록이 짧아 보이거나 에이전트가 “이게 전부입니다”라고 말함

증상: find가 예상보다 적은 행을 반환했거나, 테이블이 300개인 프로젝트에 25개라고 에이전트가 결론을 내렸습니다.

해결: 응답 봉투를 확인하십시오. 제한된 페이지는 next_cursor를 설정하고, find 도구는 잘린 목록의 이름도 truncated에 표시합니다. 둘 중 하나라도 있으면 가져올 것이 더 있다는 뜻입니다. total은 항상 전체 개수를 보고하므로 받은 행 수와 비교하십시오. 에이전트에게 커서로 페이지를 넘기거나 더 높은 limit으로 다시 실행하도록 요청하십시오.

결과가 {"_fmt": "cols", ...} 형태로 보임

증상: 도구가 예상한 객체 목록 대신 {"_fmt": "cols", "cols": [...], "rows": [[...]]}를 반환했습니다.

모든 행의 필드가 같은 큰 결과에 대한 의도된 형태이며, 필드 이름이 행마다 반복되지 않고 한 번만 전송됩니다. i번째 행은 dict(zip(cols, rows[i]))입니다. 에이전트는 연결할 때 이를 안내받으므로 별도 요청 없이 처리합니다. 직접 작성한 코드에서 이 응답을 읽는다면 작은 결과나 불규칙한 결과는 여전히 일반 객체 배열로 도착하므로 두 형태를 모두 디코딩하십시오. 봉투의 다른 부분은 바뀌지 않으며 값도 변경되지 않습니다. AI 코딩 에이전트 시작하기를 참조하십시오.

도움 받기

인증 실패, 뚜렷한 원인 없이 오류를 반환하는 도구, 누락된 도구 같은 서버 측 문제는 먼저 응답의 error 봉투를 확인하십시오. 모든 실패에는 code, retryable, message가 포함되며 hint도 자주 포함됩니다. 힌트로 충분하지 않으면 PlaidCloud 관리자에게 문의하거나, 요청 ID(X-Request-Id 응답 헤더로 반환됨)를 포함하여 지원 티켓을 여십시오.