🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
Sign In

@gency-ai/gency-mcp

Package Overview
Dependencies
Maintainers
1
Versions
10
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@gency-ai/gency-mcp

Gency AI product image generation - MCP server for Claude, Codex, Cursor, VS Code

latest
npmnpm
Version
0.6.0
Version published
Maintainers
1
Created
Source

Gency MCP

Gency MCP는 Gency AI 상품 이미지 생성 플랫폼을 Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code 같은 MCP 클라이언트에서 사용할 수 있게 해주는 공식 Model Context Protocol 서버입니다.

상품 이미지 업로드, 워크스페이스/템플릿 조회, AI 상품 이미지 생성, 크레딧 확인, 결과 이미지 다운로드를 AI 어시스턴트 대화 안에서 실행할 수 있습니다.

또한 외부 개발자가 Gency OpenAPI를 자신의 서비스에 통합하는 코드를 작성할 때 이 MCP를 보조 도구로 활용할 수 있습니다. MCP 자체는 OAuth로만 인증하며, 사용자가 직접 호출하는 REST API 통합 코드용 API Key는 developers.gency.ai에서 별도로 발급·관리합니다.

Overview

  • 기본 실행 방식: MCP stdio server
  • 패키지명: @gency-ai/gency-mcp
  • 지원 프로토콜 리비전: 2026-07-28 과 2025-11-25 동시 지원 (dual-era)
  • 인증 방식: OAuth 2.0 only — gency-mcp는 OAuth 토큰으로만 인증합니다. REST API 직접 호출용 API Key는 별도(developers.gency.ai)
  • 기본 API URL: https://openapi.gency.ai
  • 제공 기능: 21개 MCP tools (HTTP 모드는 18개), API reference resource, 상품 생성 prompt

프로토콜 호환성

클라이언트가 negotiate 하는 리비전으로 서비스합니다. 별도 설정은 필요 없습니다.

클라이언트가 요구하는 것동작
2025-11-25 이하 (initialize 핸드셰이크)그대로 동작
2026-07-28 (server/discover)그대로 동작

2026-07-28 은 프로토콜 레벨 세션과 initialize 핸드셰이크를 제거했습니다 (SEP-2567, SEP-2575). 구버전 클라이언트는 새 리비전으로 올라갈 수단이 없기 때문에 (호환성 매트릭스에서 legacy 클라이언트 → modern 전용 서버는 "Fails"), gency-mcp 는 한쪽으로 전환하지 않고 양쪽을 서비스합니다.

Use Cases

Gency MCP는 두 가지 사용 시나리오를 지원합니다.

1. AI 어시스턴트로 Gency 사용 (주 사용처)

Claude·Cursor·VS Code 같은 MCP 클라이언트 안에서 상품 이미지 업로드 → 템플릿 선택 → AI 상품 이미지 생성 → 결과 다운로드 흐름을 자연어 대화로 실행합니다. 일반 사용자, 마케팅·운영 팀이 주 대상입니다.

2. Gency OpenAPI 통합 구축 보조

외부 개발자가 Gency OpenAPI를 자신의 서비스/제품에 통합할 때, MCP에 탑재된 search_docs 툴과 api-reference 리소스를 통해 AI 어시스턴트가 엔드포인트·인증(OAuth 2.0 + PKCE, X-API-Key)·스키마·웹훅을 이해한 상태로 통합 코드 작성, 디버깅, 마이그레이션을 도와줍니다. 통합 코드가 호출할 REST API의 자격증명(API Key 또는 OAuth client)은 developers.gency.ai에서 발급받아 사용자가 자기 코드에 직접 넣어 사용합니다. MCP가 그 자격증명을 대신 보관하거나 사용하지는 않습니다.

예시:

  • "Gency create_product API 요청 본문 스키마 알려줘. TypeScript 타입으로 정의해줘."
  • "Gency 웹훅 페이로드 구조 검색하고, Express 핸들러 예제 만들어줘."
  • "OAuth 2.0 + PKCE 흐름 어떻게 되는지 docs 검색해서 우리 백엔드에 맞게 구현해줘."

Quick Start

1. MCP 서버 등록

Claude Code 예시:

claude mcp add gency -- npx -y @gency-ai/gency-mcp

모든 MCP 클라이언트에서 공유하려면 -s user, 프로젝트 단위로만 쓰려면 -s project 등 scope 옵션을 추가하세요. 기본값(local) 그대로 두면 현재 작업 디렉터리에서만 동작합니다.

다른 MCP 클라이언트에서는 command를 npx, args를 ["-y", "@gency-ai/gency-mcp"]로 등록합니다.

2. 로그인

터미널에서 OAuth 로그인을 실행합니다.

npx -y @gency-ai/gency-mcp login

브라우저에서 Gency 로그인을 완료하면 토큰이 ~/.gency/tokens.json에 저장됩니다.

3. 사용 확인

MCP 클라이언트에서 Gency 서버가 연결된 뒤 아래처럼 요청해보세요.

  • "Gency 인증 상태 확인해줘"
  • "Gency 워크스페이스 목록 보여줘"
  • "내 남은 Gency 크레딧 확인해줘"
  • "이 상품 사진들을 업로드해서 상품 이미지 생성 준비해줘"

Authentication

Gency MCP는 OAuth 2.0 (Authorization Code + PKCE) 만 사용합니다. API Key 기반 인증은 MCP 런타임에서 지원하지 않습니다.

로그인:

npx -y @gency-ai/gency-mcp login

브라우저에서 Gency 로그인을 완료하면 토큰이 ~/.gency/tokens.json에 저장되고, 이후 모든 MCP 도구 호출이 Authorization: Bearer … 헤더로 자동 인증됩니다. 만료된 액세스 토큰은 다음 호출 시 refresh token으로 자동 갱신됩니다.

로그아웃 (저장된 OAuth 토큰 삭제):

npx -y @gency-ai/gency-mcp logout

MCP 대화 안에서도 login, logout, auth_status tools를 사용할 수 있습니다.

Direct REST API 호출 (MCP 외부)

자신의 백엔드/서버 코드에서 Gency OpenAPI(https://openapi.gency.ai/openapi/v1/…)를 직접 호출하는 경우에는 API Key를 X-API-Key 헤더로 보낼 수 있습니다.

curl https://openapi.gency.ai/openapi/v1/teams/me \
  -H "X-API-Key: gency_key_…"

API Key는 developers.gency.ai 의 App 상세 페이지에서 발급·활성화·재발급합니다. 이 키는 사용자의 통합 코드에서 직접 사용하는 것이며, gency-mcp에 등록하거나 환경변수로 주입할 수 없습니다.

Client Setup

먼저 npx -y @gency-ai/gency-mcp login으로 인증을 완료한 뒤 클라이언트에 MCP 서버를 등록합니다.

Claude Code 
claude mcp add gency -- npx -y @gency-ai/gency-mcp
Codex CLI

~/.codex/config.toml에 추가합니다.

[mcp_servers.gency]
command = "npx"
args = ["-y", "@gency-ai/gency-mcp"]
Claude Desktop

claude_desktop_config.json에 추가합니다.

{
  "mcpServers": {
    "gency": {
      "command": "npx",
      "args": ["-y", "@gency-ai/gency-mcp"]
    }
  }
}
Cursor

프로젝트의 .cursor/mcp.json 또는 전역 MCP 설정에 추가합니다.

{
  "mcpServers": {
    "gency": {
      "command": "npx",
      "args": ["-y", "@gency-ai/gency-mcp"]
    }
  }
}
VS Code MCP clients

사용 중인 MCP 클라이언트 설정에 아래 값을 등록합니다.

FieldValue
Commandnpx
Args["-y", "@gency-ai/gency-mcp"]

Example Prompts

  • "Gency 인증 상태 확인하고 다음에 뭘 해야 하는지 알려줘."
  • "내 Gency 워크스페이스와 팀 정보를 보여줘."
  • "워크스페이스에서 사용 가능한 템플릿 목록을 보여줘."
  • "이 로컬 이미지 파일들을 Gency에 업로드해줘."
  • "크레딧 확인 후, 상품 이미지 생성을 진행할 수 있는지 확인해줘."
  • "생성된 상품의 다운로드 이미지를 받아줘."

상품 생성은 크레딧을 소모하고 데이터를 생성하는 작업입니다. create_product, create_workspace, update_workspace, update_product_status 같은 변경 작업은 실행 전에 사용자 확인을 받아야 합니다.

Available Tools

Gency MCP는 21개의 MCP tools를 제공합니다 (HTTP serve 모드는 login/logout/auth_status 를 제외한 18개 — HTTP Serve Mode 참고).

CategoryTools
Authlogin, logout, auth_status
Workspacelist_workspaces, create_workspace, update_workspace
Team / Userget_team, get_me, list_users, get_user
Templateslist_templates
Productslist_products, get_product, create_product, update_product_status
Imagesprepare_product_images, get_upload_url, upload_image, download_product_image
Usageget_credits
Docssearch_docs

prepare_product_images 는 get_upload_url + upload_image 를 6장 이상 한 번에 처리해주는 편의 도구입니다. 일반 사용자 플로우는 이 도구를 사용하고, 저수준 제어가 필요할 때만 개별 도구를 사용하세요.

get_upload_url 은 uploadUrl 과 함께 uploadHandle 을 반환하고, upload_image 는 URL 대신 그 handle 을 받습니다. handle 은 대상 URL·만료·호출자 신원을 HMAC 으로 묶은 값이라 목적지가 서명 안에서 나옵니다 — 임의의 로컬 파일을 임의의 HTTPS URL 로 PUT 할 수 없고, 한 호출자의 handle 을 다른 호출자가 사용할 수 없습니다.

download_product_image 는 상품 상세페이지를 렌더해 이미지 파일로 저장합니다. 저장 위치는 outputPath(절대경로)로 지정할 수 있고, 생략하면 OS 임시 디렉터리에 gency-<productId>.png 로 저장됩니다. 렌더링은 수십 초가 걸릴 수 있어 이 도구만 최대 3분까지 기다립니다.

create_product 의 category 는 현재 Gency API가 CLOTHING 만 허용합니다. 다른 값은 현재 CLOTHING 카테고리만 지원됩니다 오류로 거부됩니다.

CLI Reference

gency-mcp는 인자 없이 실행하면 MCP stdio server로 동작합니다.

CommandDescription
gency-mcpMCP stdio server 실행
gency-mcp serveMCP stdio server 명시 실행
gency-mcp setup첫 설정 OAuth 마법사
gency-mcp login [options]브라우저 OAuth login 실행 후 token 저장
gency-mcp logout저장된 OAuth token 삭제 (~/.gency/tokens.json)
gency-mcp whoami현재 OAuth token introspection 결과 출력
gency-mcp serve-http [options]HTTP MCP server 실행
gency-mcp helpCLI help 출력

Login Options

OptionDescription
--client-id <id>OAuth client ID override
--client-secret <secret>OAuth client secret override
--api-base <url>OAuth provider base URL override
--scope <scope>Space-separated OAuth scopes
--port <number>Loopback callback port, default 53682
--no-browser브라우저를 자동으로 열지 않고 authorize URL만 출력

HTTP Serve Mode

serve-http는 일반 사용자용 기본 실행 모드가 아닙니다. 원격 MCP 클라이언트나 특수 통합 환경에서 사용합니다. RFC 9728 protected-resource metadata 를 다음 두 경로에 모두 서빙합니다 (2026-07-28 부터 MCP 서버 필수 사항):

  • /.well-known/oauth-protected-resource/mcp — WWW-Authenticate challenge 가 가리키는 경로
  • /.well-known/oauth-protected-resource — 스펙의 401 예시가 쓰는 path-less 형태

authorization server metadata (/.well-known/oauth-authorization-server) 는 의도적으로 서빙하지 않습니다. 문서의 issuer 는 Gency 인데 우리 origin 에서 나오면 RFC 8414 issuer/location 불일치이고, 클라이언트는 이제 PRM 으로 AS 를 찾아야 하므로 존재 이유가 없습니다.

npx -y @gency-ai/gency-mcp serve-http --port 53683 --host 127.0.0.1
OptionDescription
--port <number>HTTP server port, default 53683
--host <addr>Listen host, default 127.0.0.1
--client-id <id>OAuth token introspection client ID
--client-secret <secret>OAuth token introspection client secret
--api-base <url>OAuth provider URL
--public-url <url>Non-loopback binding 뒤에 사용할 public HTTPS base URL
--allowed-hosts <csv>Non-loopback 요청에서 허용할 Host 값 목록
--allowed-origins <csv>Non-loopback 요청에서 허용할 browser Origin 목록

127.0.0.1, localhost, ::1 이외의 주소에 바인딩할 때는 위 세 가지 보안 옵션이 모두 필요합니다.

HTTP 모드는 stateless 입니다. 매 요청이 자기 bearer 토큰으로 인증되고, 그 토큰으로 Gency API 를 호출합니다. 세션에 결합되지 않습니다 — 2026-07-28 이 프로토콜 세션을 제거했고 Mcp-Session-Id 는 무시됩니다. 세션 조작이었던 GET /mcp 와 DELETE /mcp 는 405 를 반환합니다. 게이트웨이나 로드밸런서를 앞에 둘 때 sticky routing 은 필요하지 않습니다.

HTTP 모드에서는 login / logout / auth_status 를 노출하지 않습니다 (18개 tools). 이 세 도구는 서버 호스트의 ~/.gency/tokens.json 을 다루므로 원격 호출자에게는 의미가 없거나 위험합니다. stdio 모드는 기존처럼 로컬 로그인 정보를 사용합니다 (21개 tools).

여러 인스턴스로 수평 확장할 때는 GENCY_MCP_UPLOAD_SECRET 을 모든 인스턴스에 동일하게 설정해야 합니다 — 그러지 않으면 한 인스턴스가 발급한 uploadHandle 이 다른 인스턴스에서 검증되지 않습니다.

Configuration

Environment VariableDescriptionDefault
GENCY_API_URLGency API base URLhttps://openapi.gency.ai
GENCY_OAUTH_CLIENT_IDOAuth client ID overridebuilt-in official client ID
GENCY_OAUTH_CLIENT_SECRETOAuth client secret for confidential clientsunset
GENCY_OAUTH_API_BASEOAuth provider base URLGENCY_API_URL
GENCY_OAUTH_SCOPEOAuth scopesproduct:read product:write team:read team:write user:read
GENCY_MCP_ALLOWED_CLIENT_IDSserve-http 에서 토큰을 수락할 OAuth client ID 목록 (공백/쉼표 구분). 비어 있으면 모든 client 를 수락unset
GENCY_MCP_UPLOAD_SECRETuploadHandle 서명 키. 여러 인스턴스로 확장할 때만 필요프로세스별 랜덤
GENCY_MCP_OAUTH_RESOURCERFC 8707 resource indicator. 설정하면 authorize/token/refresh 에 resource 를 전송unset (미전송)

GENCY_MCP_ALLOWED_CLIENT_IDS 는 기본값을 켤 수 없습니다. HTTP 모드에서 원격 MCP 호스트는 자기 client_id 로 Gency 에 OAuth 하므로, 우리 introspection client_id 로 allowlist 를 만들면 정당한 호출자를 전부 거부합니다. Gency 가 introspection 에 aud 를 반환하기 전까지는, 이 값을 명시적으로 설정하는 것이 다른 Gency 클라이언트에 발급된 토큰의 재사용을 막는 유일한 수단입니다. aud 가 오면 별도 설정 없이 자동으로 검증됩니다.

GENCY_MCP_OAUTH_RESOURCE 가 opt-in 인 이유: 2026-07-28 은 클라이언트가 resource 를 보내도록 요구하지만, Gency AS 가 이를 수락하는지 검증되지 않았고 알 수 없는 resource 값을 거부하는 AS 는 모든 사용자의 로그인을 깨뜨립니다.

Credentials are stored under ~/.gency/.

PathDescription
~/.gency/tokens.jsonOAuth access/refresh token storage (mode 0600)

Troubleshooting

MCP tool says there are no credentials

OAuth로 로그인합니다.

npx -y @gency-ai/gency-mcp login

그 후 MCP 클라이언트에서 auth_status를 실행하면 현재 상태를 확인할 수 있습니다. API Key는 MCP에서 인증에 사용되지 않으므로 등록할 필요가 없습니다.

OAuth login does not open a browser

Use --no-browser and open the printed URL manually.

npx -y @gency-ai/gency-mcp login --no-browser

OAuth callback port is already in use

Use a custom port only if that redirect URI is allowed by the OAuth client.

npx -y @gency-ai/gency-mcp login --port 53684

create_product 가 "최소 6장 필요" 라고 함

상품당 이미지 최소 6장이 Gency API 요구사항입니다. prepare_product_images 도구로 한 번에 처리하면 6장 미만일 때 즉시 알려주고 업로드도 일괄 처리됩니다.

create_product 가 "추측값 사용 금지" 라고 함

colors, fabrics, features, laundryTips 에 "면 100%", "30도 이하 찬물 세탁" 같은 일반 기본값이 포함되면 validation 단계에서 차단됩니다. 사용자에게 실제 값을 확인 후 재호출하세요.

templateId 가 유효하지 않음

워크스페이스마다 사용 가능한 템플릿이 다릅니다. list_templates 를 다시 호출해 현재 워크스페이스의 템플릿 ID 목록을 확인하세요.

Token refresh 실패

auth_status 결과 introspect 가 inactive 이고 refresh 도 실패하면 토큰이 만료됐거나 폐기된 상태입니다.

npx -y @gency-ai/gency-mcp logout
npx -y @gency-ai/gency-mcp login

업로드한 이미지가 사라짐

업로드된 이미지는 create_product 호출 없이 24시간 후 자동 삭제됩니다. 업로드 후에는 그 안에 create_product 를 호출해 imageId 를 사용해야 합니다.

클라이언트가 "unsupported protocol version" 또는 서버 시작 실패를 보고함

gency-mcp 는 2025-11-25 와 2026-07-28 을 모두 서비스하므로 리비전 불일치로 이 오류가 나지는 않습니다. 확인할 것:

  • npx -y @gency-ai/gency-mcp 가 최신 버전을 받았는지 (npx --yes @gency-ai/gency-mcp@latest)
  • Node 20.3 이상인지 (node -v)
  • 클라이언트 설정이 serve-http 를 가리키는 경우, 그 URL 에 OAuth bearer 토큰을 붙이는지 — HTTP 모드는 인증 없는 요청을 401 로 거부합니다

GET /mcp 또는 DELETE /mcp 에서 405 를 받는 것은 정상입니다. 이들은 2026-07-28 이 제거한 세션 조작이며 오류가 아닙니다.

Build fails with tsc: command not found

Install dependencies first.

pnpm install
pnpm run build

Links

License

MIT License. © 2026 STUDIOLAB. All rights reserved.

Keywords

mcp
gency
ai
product-images
fashion
claude

FAQs

Package last updated on 30 Jul 2026

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

Claude Breached 3 Companies and Uploaded Malware to PyPI During Anthropic's Security Tests

Security News

Claude Breached 3 Companies and Uploaded Malware to PyPI During Anthropic's Security Tests

A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.

By Sarah Gooding  -  Jul 31, 2026
Socket Is Sponsoring Composer and Packagist

Security News

/

Company News

Socket Is Sponsoring Composer and Packagist

Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.

By Sarah Gooding  -  Jul 31, 2026