Gmail, Google Calendar, Microsoft 365를 Claude Code에 로컬 MCP 커넥터로 연결하려 하면 OAuth 흐름이 콜백에서 멈추고 토큰이 도착하지 않습니다. 설정 문제가 아닙니다. Anthropic이 등록한 리디렉션 URI 위치 때문입니다.
등록된 리디렉션 URI 때문에 Gmail과 Calendar가 localhost에서 멈춥니다
이 멈춤은 프로토콜 버그가 아니라 제공자 쪽 등록 제약입니다. Anthropic은 Microsoft 365, Gmail, Google Calendar의 OAuth 콜백을 claude.ai에만 등록해 두었기 때문에, 상위 ID 제공자는 사전 승인되지 않은 리디렉션 URI를 거부합니다. Claude Code의 로컬 MCP 클라이언트는 IdP에 등록된 적 없는 localhost 콜백에서 대기하므로, 인증 토큰이 돌아갈 곳이 없어 핸드셰이크가 완료되지 않습니다 . Claude 쪽 플래그로는 이를 우회할 수 없습니다. 승인된 URI는 사용자가 손댈 수 없는 제공자 등록 정보 안에 있습니다.
인증에 성공하는 커넥터에도 또 다른 한계가 있습니다. Claude Code는 MCP 출력이 10,000토큰을 넘으면 경고하고, 별도로 재정의하지 않는 한 기본 25,000토큰 하드 캡을 적용합니다. 개별 도구 결과가 최대 500,000자 제한을 알릴 수 있더라도 파이프라인 캡이 먼저 걸려 큰 페이로드가 잘립니다 . Anthropic이 2024년 11월 25일 오픈소스로 공개한 MCP 자체는 전송 방식에 구애받지 않습니다. 이런 제한은 Claude Code 런타임의 동작입니다 .
| 실패 유형 | 발생 조건 | 증상 |
|---|---|---|
| 리디렉션 차단 | OAuth 콜백이 localhost용으로 등록되지 않음 | 인증이 완료되지 않음 |
| 출력 초과 | 응답이 약 25,000토큰 캡을 초과 | 결과가 잘림 |
두 경우 모두 해결 방향은 같습니다. Claude가 보기 전에 인증을 완료하거나 페이로드를 줄이는 외부 래퍼를 두는 것입니다. 여기서 n8n이 역할을 합니다.
n8n MCP 도구 노드가 리디렉션 문제를 피하는 방식
이 방식이 통하는 이유는 n8n이 한 번의 UI 내 승인 후 OAuth 자격 증명을 내부에 저장하기 때문입니다. n8n 안에서 Gmail이나 Google Calendar를 연결하면 상위 핸드셰이크는 n8n 자체에 등록된 리디렉션 URL을 대상으로 완료됩니다. Claude는 리디렉션을 시작하지 않으므로 Claude Code의 로컬 OAuth를 멈추게 하는 localhost 콜백 자체가 발생하지 않습니다 .
그다음에는 자격 증명이 연결된 작업을 도구로 노출합니다. MCP Server Trigger는 n8n 인스턴스를 SSE 또는 스트리밍 가능한 HTTP 기반의 탐색 가능한 MCP 엔드포인트로 바꿉니다. stdio는 지원하지 않으며, 연결된 노드를 통해 데이터를 전달하는 대신 연결된 워크플로 도구를 실행합니다 . Claude Desktop은 mcp-remote 게이트웨이를 통해 여기에 접속합니다.
Bearer 인증을 쓰면 Claude에 제공자 자격 증명을 넣을 필요가 없습니다. 제공자의 OAuth 토큰이 아니라 공유 시크릿을 claude_desktop_config.json에 전달합니다 . 필요한 조건은 많지 않습니다.
- n8n v1.82.0 이상(AI Agent 노드는 Tools Agent로 실행되며, 연결된 도구 하위 노드가 최소 하나 필요합니다)
- ngrok 또는 Tailscale로 노출된 HTTPS 주소
- 로컬에 설치된
mcp-remote
나만의 n8n MCP 도구 노드 만들기
도구 노드를 만드는 과정은 다섯 단계입니다. 액션 워크플로를 만들고, MCP Server Trigger로 감싼 다음, 설명을 정확히 작성하고, 인증된 HTTPS로 노출한 뒤, Claude Desktop에 등록합니다. MCP Server Trigger는 일반 트리거처럼 연결된 노드로 데이터를 전달하지 않습니다. 도구 하위 노드에 연결해 실행만 합니다 . 아래 단계는 순서대로 실행할 수 있습니다.
- 액션 워크플로를 만듭니다. n8n 자격 증명 관리자에 Gmail 또는 Calendar 자격 증명을 추가합니다. 기본 MCP 서버가 이를 대신 저장해 주지 않으므로, 제공자 자격 증명은 UI에서 추가해야 합니다 . 작업(예:
create-calendar-event)을 구성하고 테스트 실행을 돌려 응답 JSON이 Claude Code의 기본 최대치인 25,000토큰 아래에 머무는지 확인합니다 . - MCP Server Trigger를 추가합니다. 새 워크플로에 MCP Server Trigger 노드를 넣고 하나 이상의 Custom n8n Workflow Tool 노드를 연결합니다. 각 노드는 데이터베이스 ID 또는 인라인 JSON으로 액션 워크플로를 가리키며, MCP 클라이언트가 발견하고 호출할 수 있는 도구가 됩니다 .
- 도구 설명을 정확히 씁니다. 설명 텍스트는 Claude가 언제 도구를 호출할지 판단할 때 읽는 내용이므로, 두 문장 이하로 유지하고 기대하는 입력값을 명시합니다. Claude가 값을 채워야 하는 모델 입력 파라미터에는
$fromAI()를 사용합니다 . 많은 원시 API 도구를 노출하는 것보다 범위가 좁고 문서화가 잘 된 도구 하나가 낫습니다. - 노출하고 인증을 설정합니다. 트리거 워크플로를 활성화하고 생성된
/mcpURL을 복사한 뒤 n8n에서 bearer token 자격 증명을 설정합니다. 자체 호스팅이라면 리버스 프록시의/mcp*경로에서 gzip, buffering, chunked transfer encoding을 비활성화해야 합니다. 그렇지 않으면 연결이 실패합니다 . - Claude Desktop에 연결합니다.
claude_desktop_config.json에/mcpURL과 bearer token을 포함한mcp-remote항목을 추가한 뒤 Claude Desktop을 다시 시작합니다 .
{
"mcpServers": {
"n8n-calendar": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-n8n-host/mcp/<workflow-id>",
"--header", "Authorization: Bearer YOUR_TOKEN"
]
}
}
}실제 호출을 실행하기 전에 Claude Desktop의 사용 가능한 도구 목록에 도구 이름이 표시되는지 확인합니다. 표시된다면 리디렉션 문제는 해결된 것이며, Claude가 해당 작업을 직접 호출할 수 있습니다(video: Hasan Aboul Hasan).
n8n MCP 도구 노드에서 예상치 못하게 걸릴 수 있는 부분
가장 흔한 함정은 클라이언트별 범위 제한이 없다는 점입니다. 같은 MCP Server Trigger 엔드포인트에 연결된 모든 MCP 클라이언트가 활성화된 모든 도구 노드를 볼 수 있습니다. 같은 인스턴스에서 Claude에는 Gmail 도구를 노출하고 다른 클라이언트에는 숨기는 식으로 나눌 수 없으므로, 활성화된 워크플로는 연결된 모든 클라이언트에 보인다고 보고 다뤄야 합니다 .
인프라 쪽에는 더 날카로운 주의점이 두 가지 있습니다. 큐 모드 배포에서는 모든 /mcp* 요청이 전용 웹훅 레플리카 하나로만 라우팅되어야 합니다. 다른 레플리카로 가면 SSE 연결이 중간에 조용히 끊깁니다. 또한 리버스 프록시는 MCP 엔드포인트에서 buffering, gzip, chunked transfer encoding을 비활성화해야 하며, 그렇지 않으면 연결 자체가 실패합니다 .
n8n의 기본 인스턴스 단위 MCP 서버(Public Preview, 2026년 4월 29일 )로 워크플로를 생성한다면, 첫 결과물에는 분기가 과하게 들어갈 수 있다고 보고 프로덕션에 올리기 전에 정리해야 합니다. 자격 증명은 자동 저장되지 않습니다. 생성된 Gmail 워크플로라도 실행이 성공하려면 UI에서 OAuth 자격 증명을 수동으로 추가해야 합니다.
"AI output is unpredictable — never let it edit production workflows directly," n8n-mcp 프로젝트의 메인테이너 Piotr Czlonkowski는 이렇게 경고합니다 (source: czlonkowski/n8n-mcp).
더 큰 흐름: czlonkowski/n8n-mcp와 2026년 4월 인스턴스 MCP
직접 만든 도구 노드 위에는 이제 두 개의 계층이 놓여 있습니다. 커뮤니티 프로젝트 czlonkowski/n8n-mcp(v2.63.0, 2026년 7월 3일 출시, GitHub 스타 약 22.1k)는 공개된 도구 23개를 통해 노드 2,063개와 템플릿 2,352개를 인덱싱합니다 . 실데이터를 건드리지 않고 Claude가 알맞은 노드를 고르도록 돕는 읽기 전용 노드 카탈로그로 가장 유용합니다. 그 위에는 n8n의 인스턴스 단위 MCP 서버가 있습니다. 2026년 4월 29일부터 Public Preview로 제공되며 Cloud, Enterprise, 무료 Community에서 사용할 수 있고, Claude Desktop, Claude Code, Codex CLI가 인스턴스당 하나의 연결로 워크플로를 만들고, 검증하고, 테스트하고, 트리거할 수 있게 해줍니다. 단, 워크플로별 활성화가 필요합니다 . 2026년 5월 19일에는 Claude가 Apify, Linear, monday.com, Notion, PostHog에 대한 원클릭 MCP 연결을 추가했습니다. 이 다섯 서비스에는 수동 MCP Client 노드가 필요하지 않습니다 .
보안의 최저선은 전반에 걸쳐 같습니다. MCP 명세는 confused-deputy OAuth 위험, 메타데이터 탐색을 통한 SSRF, 세션 하이재킹을 지적합니다 . 결론은 단순합니다. 활성화된 도구 카탈로그를 좁고 명시적으로 유지하고, 최소 권한 자격 증명을 쓰며, 쓰기 경로의 모든 작업에는 사람의 검토를 둬야 합니다. 그런 다음 Claude 자체 OAuth가 처리하지 못하는 라우팅은 카탈로그에 맡기면 됩니다.
자주 묻는 질문
이 n8n MCP 도구 우회 방식을 Claude Desktop뿐 아니라 브라우저의 Claude.ai에서도 쓸 수 있나요?
아니요. 2026년 중반 기준, 브라우저의 Claude.ai는 사용자가 설정한 MCP 서버를 지원하지 않습니다. 따라서 mcp-remote 게이트웨이와 커스텀 MCP 엔드포인트는 로컬 클라이언트인 Claude Desktop과 Claude Code에서만 작동합니다 . 이는 우연이 아닙니다. 처음부터 n8n으로 우회하게 만든 OAuth 리디렉션 정지는 이 로컬 클라이언트들에만 해당하는 문제입니다. 상위 제공자가 claude.ai의 등록된 리디렉션 URL만 허용하기 때문입니다 . 우회책과 문제가 같은 위치에 있는 셈입니다.
MCP Server Trigger와 n8n의 기본 인스턴스 단위 MCP 서버는 무엇이 다른가요?
MCP Server Trigger는 하나의 워크플로에 수동으로 붙인 특정 도구 노드만 노출합니다. 하나 이상의 Custom n8n Workflow Tool 노드를 연결하면 각각이 Claude Desktop 같은 클라이언트가 호출할 수 있는 도구가 됩니다 . 2026년 4월 29일 Public Preview에 들어간 기본 인스턴스 단위 MCP 서버는 범위가 훨씬 넓습니다. MCP 클라이언트가 전체 인스턴스에서 워크플로를 검색, 트리거, 테스트, 생성, 편집할 수 있고, 배포 전에 타입 검사를 위해 TypeScript 표현을 생성합니다 . 범위는 넓지만 여전히 게이트가 있습니다. 워크플로는 개별적으로 활성화해야 하며, 검색 결과는 기본값과 최대값이 모두 200입니다 .
Gmail 쿼리에서 메시지 수백 개가 반환될 때 25k 토큰 출력 한도에 걸리지 않으려면 어떻게 해야 하나요?
Claude에 반환한 뒤가 아니라, n8n 워크플로 안에서 먼저 잘라내야 합니다. Claude Code는 MCP 출력이 10,000토큰을 넘으면 경고하며, 별도로 재정의하지 않으면 기본 최대값은 25,000토큰입니다 . 이 한도는 도구 수준 annotation 없이는 호출별로 설정할 수 없습니다. 올바른 절단 지점은 n8n 워크플로입니다. 메시지 ID와 제목만 반환하거나, 가장 최근 N개 항목만 반환하고, 에이전트가 후속 호출에서 특정 메시지의 상세 내용을 요청하게 하세요. 서버 측에서 페이지네이션하거나 필터링하면 모든 응답을 한도보다 충분히 작게 유지할 수 있습니다.
czlonkowski/n8n-mcp를 프로덕션 n8n 인스턴스에 연결해도 안전한가요?
읽기 전용 모드일 때만 그렇습니다. 2026년 7월 3일 v2.63.0을 출시했고 GitHub 스타가 약 22.1k에 이른 czlonkowski/n8n-mcp의 메인테이너는 AI 출력은 예측할 수 없으므로 프로덕션 워크플로를 직접 편집하게 해서는 안 된다고 경고하며, 환경 변수로 읽기 전용 배포를 강제할 수 있다고 설명합니다 . 이 프로젝트의 도구 23개 중에는 N8N_API_URL과 N8N_API_KEY가 필요하고 쓰기 권한이 부여되면 워크플로를 수정할 수 있는 관리 도구 16개가 포함됩니다 . 쓰기 가능한 MCP 접근은 별도의 비프로덕션 인스턴스에서만 사용하세요.
이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.
