shared-skill-mcp

claude.ai 맞춤 커넥터를 위한 AWS 호스팅 MCP 서버로, 시간이 지남에 따라 하나 이상의 도구를 담을 수 있도록 설계되었습니다. 처음 시작한 Google Sheets 쿼리 도구에 국한되지 않습니다. 하나의 공유 Cognito 인증 레이어(Google 로그인) + 하나의 Bedrock AgentCore Gateway(실제 MCP 서버) + 도구별 Lambda 하나로 구성됩니다.

원래 query_sheet 도구에 대한 전체 스펙, 아키텍처 다이어그램, 단계별 기록은 다음에서 확인할 수 있습니다: Reel AI Workers/skills-spec/sheet-gviz/sheet-gviz.md.

상태 (2026-08-24)

실제 claude.ai 커넥터가 Google 로그인을 완료하고 도구를 호출하는 것까지 포함하여, 엔드투엔드로 정상 동작이 확인되어 운영 중입니다 — 단순한 curl이 아니라 실제 커넥터로 확인한 상태입니다.

현재 값(시크릿 포함)은 언제든 얻을 수 있습니다:

AWS_PROFILE=<your profile> terraform -chdir=terraform output
AWS_PROFILE=<your profile> terraform -chdir=terraform output -raw cognito_client_secret

현재 노출되어 있는 도구: query_sheet — gviz 쿼리(SQL과 유사: select/where/group by/pivot/order by)를 Google Sheets에 대해 실행합니다.

Related MCP server: Google Workspace MCP

아키텍처

claude.ai connector
      │  OAuth 2.1 (real Google login, via Cognito's Hosted UI)
      ▼
Cognito User Pool ──federates to──> Google (login only)
      │  issues an access token (no "aud" claim — see gotcha below)
      ▼
AgentCore Gateway (CUSTOM_JWT authorizer, matches by client_id)
      │  invokes under its own service role
      ▼
Lambda tool target (gateway-tool-handler.mjs) ──> gviz.js ──> Google Sheets API

두 개의 Google OAuth 클라이언트가 존재하며, 반드시 구분되어 있어야 합니다. 하나는 Cognito가 로그인용(페더레이션 자격 증명, federated identity)으로 사용하고, 하나는 gviz.js가 Sheets를 읽는 데 사용합니다(서비스 자격 증명, refresh-token 기반이며, 인터랙티브하게 사용하지 않음). 두 용도에 같은 클라이언트를 재사용하는 것은 의도적으로 피했습니다 — 스펙 문서의 “two identities” 프레임을 참고하세요.

이 저장소가 지금의 상태까지 오게 된 배경 (인증 설정을 변경하기 전에 읽을 가치가 있습니다)

처음 동작한 버전에서는 직접 구현한 Lambda Function URL을 MCP 서버로 사용했고, Lambda 자체가 Cognito JWT를 검증하고 OAuth 2.0 discovery metadata(RFC 9728 / RFC 8414)를 직접 제공했습니다. curl과 수동 Postman OAuth flow에서는 동작했습니다 — 전체 왕복, 실제 Google 로그인, 실제 Sheets 데이터까지 말이죠 — 하지만 claude.ai의 실제 커넥터 클라이언트는 그때마다 조용히 실패했습니다(Couldn’t connect / Authorization failed). 실패 원인을 알 수 있는 신호가 전혀 없었습니다. Lambda 로그를 보면 claude.ai가 discovery metadata를 한 번 가져온 뒤에는 포착된 것 — 토큰 교환도, 오류도, 아무것도 없었습니다.

당시의 추측은 다음과 같습니다. Cognito의 액세스 토큰에는 aud 클레임이 포함되지 않습니다(이는 사람이 직접 확인한 실제 Cognito 제약 사항입니다). 그리고 MCP 스펙은 클라이언트가 보내는 resource 파라미터가 해당 클레임에 반영되어야 한다고 기대합니다. 생태계의 다른 곳에서 나온 최근의 그럴듯한 증거들도 정답을 뒷받침하는 것처럼 보였습니다. 하지만 실제로는 오해였습니다. 다른 프로젝트에서 나온, 신뢰할 만도(참조용) 작업 구현 — 같은 사람이 만든 다른 저장소 — 가 Cognito + claude.ai 커넥터가 잘 동작한다는 것을 증명했습니다. 직접 구현한 서버 대신 Cognito 앞에 Bedrock AgentCore Gateway를 두었고, allowed_audience가 아닌 allowed_clients(Cognito의 client_id)로 호출자를 매칭하는 CUSTOM_JWT authorizer를 사용한 것입니다. 원래 실패의 정확한 근본 원인은 최종적으로 밝혀지지 않았습니다 — 대부분 직접 구현한 JSON-RPC/discovery 구현이 claude.ai의 클라이언트가 기대하는 것과 정확히 일치하지 않은 부분 때문이었을 가능성이 높습니다. 그런데도 그 구현은 모든 수동 테스트를 통과했었습니다.

교훈: curl과 Postman 테스트를 통과하는 스펙으로 보이는 직접 구현 MCP 서버는 claude.ai의 실제 클라이언트에 동작하는 것을 보장하지 않습니다. 두 사이에는 오류 신호가 전혀 없는 어긋남이 ställen 수 있습니다. MCP와 OAuth 2.0 discovery를 직접 구현하는 대신 AWS의 자체 MCP 구현인 Bedrock AgentCore Gateway를 선호하세요. 그러면 AWS 서비스를 하나 더 배워야 하고 현재 Terraform 프로바이더텅 여전히 닦이 커 있는 단점이 있지만요(아래 “Gotchas” 참고).

직접 구현했던 Function URL 서버(sheets-gviz-mcp Lambda, modules/mcp-lambda, src/lambda-handler.mjs, src/auth.mjs)는 Gateway가 작동하는 것이 확인된 이후 폐기했습니다 — Terraform으로 내린으며, 여전히 사용 중이고 Gateway 경로가 그대로 재사용하는 Cognito User Pool/도메인/app client에는 전혀 영향 없이 repo에서 삭제했습니다. 남은 reasoning 등 필요한 상황이 다시 오면, git history에 보존되어 있습니다.

그 과정에서 겪은 Gotchas (코드에서는 반영했고, 이 다시 만지려 하기 전에 알면 좋은 것입니다)

Sheets/gviz 레이어 (src/gviz.js):

1. OAuth 토큰에는 .../auth/spreadsheets와 .../auth/spreadsheets.readonly 스코프가 모두 필요합니다. readonly만 사용하면 401 오류가 표시되는데, 깔끔한 오류가 아니라 HTML 로그인 페이지처럼 보입니다.

2. gviz의 /tq 엔드포인트에는 OAuth Bearer 인증에도 /a/<domain>/ 이라는 경로 세그먼트가 필요합니다 — docs.google.com/a/google.com/spreadsheets/d/<id>/gviz/tq 같은 형식이요. google.com이 자신의 계정 도메인과 맞지 않으면 GVIZ_DOMAIN_SEGMENT에서 설정할 수 있습니다.

3. 항상 headers=1을 전달해야 합니다(querySheet 안에 하드코딩되어 있습니다). 없으면 gviz의 헤더 행 자동 감지가 잘못 크고, 실제 데이터 행을 하나의 문자열로 묶어랑 cols[].label로 숨겨버릴 수 있습니다.

AWS/테라폼 레이어:

4. IAM identity-policy 변경은 실제 적용되는 데수십 초에서 몇 분이 걸릴 수 있습니다. aws iam simulate-principal-policy는 즉시 올다고 확인해도 마찬가지를 기법. 새 작업을 부여한 직후 신생 plan/apply 첫 실행 때 403 이 일어날 수 있습니다. 문제가 있어서가 아니니, 짧게 기달렸다 재시도만 하면 됩니다.

5. ESM .js 파일은 저장소 루트의 것이 없이 zip으로 압축하면 그것만의 package.json({"type": "module"})이 필요합니다. gviz.js는 export/import 문을 사용하므로, 모든 Lambda zip 오른쪽 같은 위치에 그 파일(src/package.json)이 있어야 ESM으로 해석됩니다.

6. aws_bedrockagentcore_* Terraform 리소스는 최근에 만들어졌고 여전히 계속 변화 중입니다. 기도 문서베로그가 시차 지고는 것보다는 네가블 provider의 자체 스키마(terraform providers schema -json)를 이용해서 실제 인자 형을 확인하세요. provider >= 6.0이 필요합니다.

7. AgentCore Gateway의 CUSTOM_JWT authorizer는 allowed_audience가 아니라 allowed_clients(Cognito의 client_id)로 호출자를 매칭합니다. 이 덕분에 aud 클레임의 없는 비표준 Cognito access token에 추가 토큰 발행하는 레이어 없이도 동작할 있습니다.

8. 실제(실절인) Terraform 리소스를 모듈로 재구성하게 되면 리소스가 파괴되어 사용 수 있습니다. Phase 4→module 리팩터링과 그다음의 Function URL 폐기 폐기 모두, 매번 apply 전에 terraform state mv와 실제 plan 확인(지속해야 할 모든 것을 destroy 0건)을 했습니다. 그렇게 claude.ai가 이미 자격 증명을 가지로 있는 client는 같은 방식을 두 번 재사용해도 한 번도 파괴/재생성되지 않았습니다.

설정

1. Sheets 자격 증명이 작동하는지 확인 (독립 실행, AWS 불필요)

cp .env.example .env   # fill in GOOGLE_CLIENT_ID/SECRET/REFRESH_TOKEN, SPREADSHEET_ID
node scripts/phase1-test.mjs "select *"

“끝난 것으로 판단하는 시점”: 실제 쿼리에 대해 {columns, rows}가 출력되는 때입니다. 여기서 실패하면 Google 쪽 문제입니다(스코어, 공유 설정, Sheets API 미사용) — AWS를 만지기 전에 가장 저가로 잡을 수 있는 지점입니다.

2. Cognito + Gateway + 도구 Lambda 배포

terraform/tf/iam-policy.json에 나온 권한이 있는 AWS 자격 증명와 Cognito 로그인을 위한 두 번째 Google OAuth 클라이언트(웹 앱, Sheets 읽기용과는 분리된 것)가 필요합니다. 그 Second 클라이언트의 redirect URI를 지정하려면 Cognito의 도메인이 필요한데, 이 도구는 아직 존재하지 않습니다. 이 닥-실식 문제를 부부 적용(apply)으로 먼저 풀어야 합니다:

scripts/tf.sh apply -target=module.auth.aws_cognito_user_pool.this \
  -target=module.auth.aws_cognito_user_pool_domain.this

Google OAuth client를 redirect URI https://<gateway domain 직접 출력>/oauth2/idpresponse로 생성하세요. 그런 다음 .env에 GOOGLE_LOGIN_CLIENT_ID/GOOGLE_LOGIN_CLIENT_SECRET을 입력하세요.

scripts/tf.sh apply

CLAUDE_OAUTH_REDIRECT_URI는 설정할 필요가 없습니다. 기본값인 https://claude.ai/api/mcp/auth_callback이 실제 실제 커넥터에서 작동함을 확인했습니다.

3. 커넥터로 claude.ai에 추가

클라우드에서 claude.ai Settings(설정) → Connectors(커넥터) → Add custom connector(사용자 지정 커넥터 추가)를 선택:

• Server URL: gateway_url 출력 값

• Advanced settings(고급 설정) → OAuth Client ID/Secret: cognito_client_id / cognito_client_secret 출력 값

Cognito의 Hosted UI에서 실제 Google 로그인을 수행하고, 이후 Claude가 도구 채팅 부에서 query_sheet를 호출하는 토큰이 표시됩니다.

새 도구 추가

1. AgentCore Lambda-target 계약에 맞는 Lambda handler를 작성합니다. event가 바로 도구의 인자로 전해지며, JSON-RPC 래핑이 없습니다(Gateway가 MCP 프레이밍을 처리합니다). 패턴은 src/gateway-tool-handler.mjs를 보면 됩니다.

2. main.tf에 module "..." { source = "./modules/gateway-tool-lambda" ... } 블록을 추가하세요.

3. 필요한 대상에 대해 aws_bedrockagentcore_gateway_target 블록을 합니다 — 그 대상이 modules/agentcore-gateway 자체를 확장하면, 아니면 module.gateway.gateway_id를 가리키는 리소스를 main.tf에 직접 추가합니다.

새 Google OAuth 클라이언트, 새 Cognito 도메인, 새 Gateway 불필요합니다 — module.auth와 module.gateway의 모든 것을 이어져 사용합니다.

구조

src/
  gviz.js                  Sheets-reading logic — token refresh, gviz query, response
                            parsing. Host-agnostic; used by gateway-tool-handler.mjs.
  gateway-tool-handler.mjs AgentCore Gateway Lambda-target contract for query_sheet —
                            flat event-in/JSON-out, no JSON-RPC framing (Gateway
                            handles MCP protocol translation itself).
  package.json              {"type": "module"} — required for gviz.js's ESM syntax to
                            resolve once zipped alone, without the repo root's
                            package.json alongside it.
scripts/
  phase1-test.mjs           Standalone local proof the Sheets credential + gviz query
                            round-trip works, no AWS involved.
  tf.sh                     Wraps `terraform` with GOOGLE_*/Cognito vars sourced from
                            .env — use this instead of calling terraform directly.
terraform/
  main.tf                   Root — provider, variables, the shared auth module, the
                            claude.ai connector's Cognito app client, the Gateway, and
                            the query_sheet tool Lambda.
  modules/mcp-auth/         Cognito User Pool + Google identity provider + Hosted UI
                            domain. Shared — instantiate once per AWS account.
  modules/agentcore-gateway/ The Gateway (CUSTOM_JWT authorizer) + the query_sheet
                            Gateway Target. Extend for more targets, or add more
                            gateways for a genuinely separate trust boundary.
  modules/gateway-tool-lambda/ A standalone tool Lambda for a Gateway target — no
                            Function URL, no public permissions, no own Cognito
                            client. Gateway is the only caller, via its service role.
  iam-policy.json            Deploy-time IAM policy for whatever AWS identity runs
                            scripts/tf.sh. Broad on bedrock-agentcore:* deliberately —
                            that service/provider surface is new and evolving.