eroq MCP 서버에 OAuth 로그인 도입, 이제 키 없이 연결

이번 달 전까지 eroq를 AI 앱에 연결하려면 설정 파일에 API 키를 붙여 넣어야 했어요. 헤더를 보낼 수 없는 앱이라면 키를 URL에 넣었고요. 작동은 했지만 방식이 틀렸어요. 채팅 앱 설정에 들어간 키는 엉뚱한 곳에 놓인 비밀 값이고, 아무도 교체하지 않으니까요. 이제 https://eroq.ai/mcp의 원격 MCP 서버가 제대로 된 로그인을 지원해요. Connect를 누르고, eroq.ai에서 로그인하고, Allow를 누르면 끝이에요. 이 글에서는 작동 방식, 앱이 받는 것, 그리고 이참에 도구에서 바뀐 점을 정리해요.

앱이 받는 것

Allow를 클릭하면 eroq는 그 앱을 위해 평범한 eroq_sk_… 키를 발급하고 앱 이름을 붙여요. Claude (connected), Cursor on studio-mac (connected)처럼요. 그리고 이 키를 앱의 액세스 토큰으로 건네요. 이 키는 다른 키와 마찬가지로 개발자 → API 키에 표시돼요. 거기서 폐기하면 연결이 즉시 끊기고, 다시 연결하면 새 키가 발급돼요. 같은 이름의 앱을 다시 연결하면 이전 키를 대체하므로, 노트북을 잃어버려도 폐기 한 번이면 깔끔하게 정리돼요.

세션 테이블도, 리프레시 토큰도, 별도의 신원도 없어요. 앱은 키로 /mcp와 /v1을 호출하므로 결제, 워크스페이스 역할, 요청 한도, 이용 정지, 폐기가 직접 만든 키와 똑같이 작동해요. MCP 페이지에 앱별 버튼이 있어요.

궁금한 분을 위한 흐름

표준 OAuth 2.1이에요. 그래서 MCP 인증 사양을 따르는 클라이언트라면 저희 쪽에서 클라이언트마다 코드를 따로 짜지 않아도 모두 작동해요.

1. 앱이 토큰 없이 POST /mcp를 호출하면 401과 함께 WWW-Authenticate 헤더를 받아요. 이 헤더는 /.well-known/oauth-protected-resource를 가리키고, 그 문서는 다시 /.well-known/oauth-authorization-server를 가리켜요.
2. 앱이 스스로를 등록해요. 이름과 리디렉션 URI를 담아 POST /oauth/register(RFC 7591 동적 등록)를 호출하고 client_id를 받아요. ChatGPT는 등록 방식이 달라요. ChatGPT의 client_id는 ChatGPT가 호스팅하는 메타데이터 문서의 URL이고, 저희가 그 문서를 가져와 검증해요.
3. 앱이 PKCE 챌린지(S256, 필수)를 담아 브라우저에서 GET /oauth/authorize를 열어요. 필요하면 로그인하고, « App wants to use your eroq account »(앱이 eroq 계정을 사용하려고 해요) 화면을 확인한 뒤 Allow를 클릭해요.
4. 앱이 POST /oauth/token에서 PKCE 검증값(verifier)과 함께 코드를 교환하고 키를 받아요. 코드의 유효 시간은 2분이고, 클라이언트, 리디렉션 URI, 챌린지에 묶여 있어요.
5. 앱 쪽에서 연결을 끊으면 그 키로 POST /oauth/revoke를 호출해요.

client_id는 등록 정보를 서명해 담은 데이터 덩어리예요. 인터넷의 누구나 등록할 수 있으니 테이블을 두면 스팸만 쌓이거든요. 인가 코드는 키 자체를 봉인한 것으로, 특정 요청에 묶여 있고 수명도 짧아요. 새로 준비할 인프라도 없고, 존재하지도 않는 데이터베이스에서 유출될 것도 없어요.

키는 여전히 쓸 수 있어요. OAuth 흐름이 없는 스크립트와 클라이언트는 Authorization: Bearer eroq_sk_…를 보내고, 헤더를 보낼 수 없는 클라이언트는 https://eroq.ai/mcp/<key>를 써요. 이때는 그 URL 자체가 비밀 값이에요. Codex CLI는 eroq CLI를 로컬 stdio 서버로 쓰고, 키는 환경 변수에 넣어 둬요.

앱별 연결 방법

• Claude(웹, 데스크톱): Claude 페이지에서 한 번 클릭하면 eroq URL이 채워진 ‘Add custom connector’(커스텀 커넥터 추가) 창이 열려요. Add, Connect, Allow 순서로 누르세요.
• ChatGPT: 개발자 모드(Plus, Pro, Business, Enterprise, Edu)에서 URL로 앱을 만들고 OAuth를 고르세요. 자세한 과정은 ChatGPT 가이드에 있어요.
• Claude Code: claude mcp add --transport http eroq https://eroq.ai/mcp를 실행한 다음 /mcp → eroq → Authenticate를 선택하세요. 플러그인을 써도 돼요.
• Cursor와 VS Code: 각 페이지에 원클릭 설치 링크가 있고, 로그인은 처음 쓸 때 진행돼요. 둘 다 에디터 가이드에서 다뤄요.

도구에서 바뀐 점

도구 목록은 그대로 10개예요. generate_image, get_image_status, generate_video, get_video_status, generate_speech, enhance_prompt, list_models, list_voices, list_characters, get_account. 이 도구들로 무언가를 만들었다면 알아 둘 만한 변경이 세 가지 있어요.

이미지가 그림으로 돌아와요. generate_image는 렌더를 대기열에 넣고(이제 /v1에서는 이미지도 동영상처럼 비동기이고, 테이크 하나에 작업 하나예요), 호출 안에서 상태를 확인한 뒤(요청 시간 한도보다 한참 짧아요) 이미지를 인라인으로, 30분 동안 유효한 서명 링크와 함께 돌려줘요. 렌더는 라이브러리에도 남아요. 채팅 앱은 도구가 돌려준 이미지는 보여 주지만 URL을 직접 가져오는 일은 드물어서, 대화에 실제로 나타나는 건 인라인 이미지예요. 콜드 스타트가 느리면 작업 ID를 돌려주니, 무료인 get_image_status로 확인하면 돼요. 새 aspect 파라미터는 1:1, 3:4, 4:3, 9:16, 16:9를 받고, 가격은 같아요.

동영상은 라인업을 알아요. generate_video는 16개 엔진 중 하나를 고르는 model(기본값은 Seedance 2.0 Mini), 그 엔진이 지원하는 resolution, 사운드트랙이 있는 엔진에서 쓰는 audio 스위치, 이미지 투 비디오를 지원하는 엔진에서 첫 프레임으로 쓰는 reference_image_url을 받아요. list_models의 가격은 손으로 적은 숫자가 아니라 결제 함수에서 나와요. 5초 클립은 기본 엔진에서 45 크레딧, Kling 3.0에서 170 크레딧, Veo 3.1 Fast에서 135 크레딧이에요. 일부 엔진은 특정 플랜이 필요하고, 어떤 엔진인지 목록에 나와요.

ChatGPT가 인증 방식을 알아봐요. 도구 목록에 각 도구의 OAuth 보안 스킴이 선언돼 있어서, ChatGPT가 이를 보고 « connect » UI를 띄워요. 다른 클라이언트는 이 필드를 무시해요.

자주 묻는 질문

액세스 토큰이 진짜 API 키인가요?

네. 앱 이름이 붙은 평범한 키이고, 내 워크스페이스에 있어요. 바로 그게 핵심이에요. 자격 증명은 한 종류, 폐기하는 곳도 한 곳, 결제와 역할도 어디서나 같아요.

직접 만든 키도 계속 쓸 수 있나요?

네. Bearer 헤더로 보내거나, 헤더를 보낼 수 없는 클라이언트라면 URL에 넣으면 돼요. OAuth는 지원하는 앱의 기본 방식일 뿐, 필수는 아니에요.

앱은 내 계정에서 무엇을 볼 수 있나요?

그 키로 호출할 수 있는 것만 봐요. 생성 도구, 무료 조회, 잔액이에요. 비밀번호는 절대 보지 못해요. 로그인은 eroq.ai에서 이뤄지니까요.

연결하는 데 비용이 드나요?

아니요. 호출에는 스튜디오와 같은 가격이 적용돼요. Krea 2 이미지 한 장에 10 크레딧, Seedance 2.0 Mini 5초 클립에 45 크레딧이고, 실패한 렌더는 자동으로 환불돼요.

eroq.ai/mcp에서 쓰는 앱을 고르세요. 헤더 방식과 CLI 방식은 MCP 문서에 있어요.