MCP 연결하기

주소와 인증

두 서버 모두 JSON-RPC 2.0 을 HTTP POST 로 받습니다. 주소는 언제나 api.gujo.ai·design.gujo.ai 입니다. gujo.ai/api/... 로 부르면 MCP 헤더가 전달되지 않고, 로그인으로 받은 토큰도 api.gujo.ai 주소에서만 통합니다.

이 문서는 고객 MCP 를 다룹니다. 디자인 MCP 는 Design Gallery에 있습니다.

로그인으로 연결

클라이언트에 서버 주소만 넣습니다. 키를 만들거나 환경 변수에 넣을 필요가 없습니다.

1. 아래에서 클라이언트를 골라 설치 버튼을 누르거나 명령·설정을 넣습니다.
2. 클라이언트가 서버를 처음 부르면 브라우저가 열리고 account.gujo.ai 로그인 화면이 나옵니다. 이미 로그인해 있으면 바로 동의 화면이 나옵니다.
3. 동의 화면에서 앱 이름, 앱의 주소, 연결할 서버, 줄 권한을 확인하고 승인합니다.
4. 클라이언트가 토큰을 받아 보관하고, 그 뒤로는 만료되면 스스로 갱신합니다.

클라이언트는 서버가 알려 주는 표준 메타데이터(/.well-known/oauth-protected-resource/api/mcp)로 로그인할 곳을 스스로 찾습니다. 앱 등록도 클라이언트가 알아서 합니다.

권한

동의 화면의 권한은 계정 API 키의 능력과 이름이 같고, 판정도 키와 똑같이 합니다.

• 기본 권한은 mcp.read(MCP 연결)와 products.read(라이브러리·상품 읽기)이고, 동의하면 늘 들어갑니다.
• 앱이 orders.read·subscriptions.read·device.install 같은 권한을 더 청하면, 그 권한은 체크하지 않은 채로 나옵니다. 직접 체크한 권한만 들어갑니다.
• 도구 목록에는 준 권한으로 부를 수 있는 도구만 나옵니다. 권한이 모자란 도구를 부르면 서버가 403 과 함께 모자란 권한을 알려 주고, 앱은 그 권한으로 다시 동의를 청할 수 있습니다.
• 운영자 능력은 청할 수 없습니다.

토큰 수명과 연결 끊기

• 접근 토큰은 1시간 동안 쓸 수 있고, 클라이언트가 갱신 토큰으로 새로 받습니다. 갱신할 때마다 두 토큰이 모두 바뀝니다.
• 갱신 토큰은 30일 동안 쓰지 않으면 만료됩니다. 연결은 동의한 날부터 90일 뒤 끝나고, 그때 한 번 더 로그인합니다.
• 로그인으로 연결한 앱은 계정 보안 설정의 연결된 앱 에 보입니다. 앱 이름, 권한, 마지막 사용 시각을 보고 연결 끊기 를 누르면 그 앱의 토큰이 모두 폐기됩니다.
• 한 계정에 살아 있는 연결은 20개까지입니다. 다 찼으면 쓰지 않는 연결을 끊습니다.
• 로그인으로 받은 토큰은 MCP 에서만 씁니다. 같은 토큰으로 다른 계정 API(/api/products 등)를 부르면 401 입니다.

키로 붙이기 (CI·스크립트용)

브라우저로 로그인할 수 없는 곳(CI, 서버의 스크립트, 헤드리스 에이전트)에서는 계정 API 키를 씁니다. 아래 클라이언트별 안내의 키로 붙이기 를 펼치면 설정이 있습니다.

설정 어디에도 키 값이 들어가지 않습니다. 설정은 환경 변수(GUJO_API_KEY, GUJO_DESIGN_TOKEN)나 클라이언트의 비밀번호 입력 칸을 가리킬 뿐입니다. 키는 계정 API 키 문서대로 mcp.read 능력을 골라 만들고, 만들 때 한 번 보이는 값을 셸 환경 변수에 넣습니다.

export GUJO_API_KEY="여기에 키"

클라이언트별 연결

{
    "mcpServers": {
        "gujo": {
            "url": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "mcpServers": {
        "gujo": {
            "url": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_API_KEY}"
            }
        }
    }
}

{
    "servers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "inputs": [
        {
            "type": "promptString",
            "id": "gujo-token",
            "password": true,
            "description": "Gujo account API key (mcp.read)"
        }
    ],
    "servers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${input:gujo-token}"
            }
        }
    }
}

claude mcp add --transport http gujo https://api.gujo.ai/api/mcp

{
    "mcpServers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "mcpServers": {
        "gujo": {
            "type": "http",
            "url": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${GUJO_API_KEY}"
            }
        }
    }
}

codex mcp add gujo --url https://api.gujo.ai/api/mcp
codex mcp login gujo

[mcp_servers.gujo]
url = "https://api.gujo.ai/api/mcp"
bearer_token_env_var = "GUJO_API_KEY"

https://api.gujo.ai/api/mcp

URL: https://api.gujo.ai/api/mcp
Authorization: Bearer <GUJO_API_KEY>

{
    "mcpServers": {
        "gujo": {
            "serverUrl": "https://api.gujo.ai/api/mcp"
        }
    }
}

{
    "mcpServers": {
        "gujo": {
            "serverUrl": "https://api.gujo.ai/api/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_API_KEY}"
            }
        }
    }
}

{
    "mcpServers": {
        "gujo-design": {
            "url": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_DESIGN_TOKEN}"
            }
        }
    }
}

{
    "inputs": [
        {
            "type": "promptString",
            "id": "gujo-design-token",
            "password": true,
            "description": "Gujo design agent token"
        }
    ],
    "servers": {
        "gujo-design": {
            "type": "http",
            "url": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${input:gujo-design-token}"
            }
        }
    }
}

{
    "mcpServers": {
        "gujo-design": {
            "type": "http",
            "url": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${GUJO_DESIGN_TOKEN}"
            }
        }
    }
}

[mcp_servers.gujo-design]
url = "https://design.gujo.ai/mcp"
bearer_token_env_var = "GUJO_DESIGN_TOKEN"

{
    "mcpServers": {
        "gujo-design": {
            "serverUrl": "https://design.gujo.ai/mcp",
            "headers": {
                "Authorization": "Bearer ${env:GUJO_DESIGN_TOKEN}"
            }
        }
    }
}

연결 확인

1. 에이전트에게 도구 목록을 물으면 준 권한(키면 키의 능력)으로 부를 수 있는 도구가 나옵니다.
2. 로그인 창이 뜨지 않으면 주소가 https://api.gujo.ai/api/mcp 인지 확인합니다. Claude Code 는 /mcp, Codex 는 codex mcp login gujo 로 로그인을 다시 시작합니다.
3. 키로 붙였을 때 401 이면 키를, 403 missing_api_key_ability 면 키의 mcp.read 능력을 확인합니다.
4. 키로 붙였는데 도구가 비어 있으면 클라이언트가 환경 변수를 읽지 못한 것일 수 있습니다. 그 변수가 있는 셸에서 클라이언트를 다시 실행합니다.

도구 묶음

도구를 한꺼번에 다 보이면 에이전트가 도구를 고르기 어려워지므로, 도구는 묶음(toolset)으로 나뉘어 있습니다. 처음 tools/list 에는 메타 도구 세 개와 library 묶음의 도구만 나옵니다.

묶음을 켜고 끄면 서버가 notifications/tools/list_changed 를 보냅니다. 클라이언트가 Accept: text/event-stream 을 보냈으면 같은 응답을 SSE 로 보내 그 알림 다음에 결과를 싣습니다. 모르는 묶음 이름은 unknown_toolset 도구 오류입니다.

도구 하나는 계정 API 의 문 하나입니다. 도구 이름, 필요한 능력, 입력 칸은 API 참조의 tool 칸과 같습니다. 구매한 상품의 상세와 매뉴얼은 products_detail 로 읽습니다.

• 도구 목록에는 키에 그 문의 능력이 있는 도구만 나옵니다. 예를 들어 orders.read 가 없는 키에는 orders 묶음 도구가 보이지 않습니다.
• 이용권과 상품 범위 키 조건은 인자를 받아야 판정되므로, 부를 때 403 product_entitlement_required 같은 도구 오류로 돌아옵니다.
• 쓰기 도구 세 개(products_setup_progress_update, device_installs_create, device_usage_create)는 승인 없이 바로 실행됩니다.
• 키를 스스로 폐기하는 문과 새 키 원문을 돌려주는 문, 파일을 올리는 문, JSON 이 아닌 응답(번들 파일 같은)은 도구로 싣지 않습니다.

세션

1. initialize 응답 머리글의 Mcp-Session-Id 를 받습니다. 프로토콜 버전은 2025-11-25 입니다.
2. 그 뒤 요청에는 같은 Mcp-Session-Id 를 싣습니다. 켠 묶음은 세션마다 기억됩니다.
3. 세션은 쓸 때마다 12시간씩 늘어납니다. 모르는 세션이나 다른 키의 세션이면 HTTP 404 와 JSON-RPC -32600 이 오고, 그때는 initialize 부터 다시 합니다.

세션 머리글 없이 부르는 요청은 library 묶음만 켠 것으로 봅니다. 배치 요청은 받지 않고(400), 지원하는 메서드는 initialize·ping·tools/list·tools/call 과 알림(202 빈 본문)입니다.

결과와 오류

• 성공: structuredContent = {status, body}. status 와 body 는 그 문을 REST 로 불렀을 때의 HTTP 상태와 JSON 본문입니다.
• 실패: isError: true, structuredContent = {error, message, status?, body?, field?}. error 는 그 문의 오류 코드(product_entitlement_required 등)이거나, 입력 칸과 맞지 않는 인자면 invalid_input(field 에 그 칸)입니다.
• 보이지 않는 도구 이름을 부르면 JSON-RPC 오류 -32602 Unknown tool 입니다. 예전에 쓰던 mcp_tool_{id} 꼴의 이름도 이제는 이 오류입니다.
• 모르는 메서드는 -32601 입니다.

문제 해결