# 외부 에이전트용 MCP-GATEWAY 연결 가이드

외부 AI 에이전트가 mcp-gateway MCP 서버에 연결하기 위한 단계별 가이드입니다.

## 진행 순서 및 시작 전 확인

전체 단계는 다음 순서로 진행됩니다.
1. PlayMCP 회원 로그인 (사용자 수행)
2. One Time Token 및 연결 프롬프트 생성 (사용자 수행)
3. mcporter 설치 (에이전트 수행)
4. MCP 서버 정의 추가 (에이전트 수행)
5. 액세스 토큰 발급 (에이전트 수행)
6. 인증 정보 설정 (에이전트 수행)
7. 연결 완료 및 검증 (에이전트 수행)

**먼저 One Time Token(OTT) 보유 여부를 판단하세요.**
- 이미 OTT 값을 알고 있다면 (예: 사용자 메시지에 `oneTimeToken: ...` 이 포함되어 있는 경우): 아래 1, 2번을 건너뛰고 **"3. mcporter 설치"부터 진행**하세요.
- OTT가 없다면: 아래 1, 2번 내용을 **사용자에게 안내**하고, 사용자가 새 연결 프롬프트를 붙여넣을 때까지 대기하세요. 1, 2번은 웹사이트에서의 사용자 동작이므로 AI 에이전트가 직접 수행할 수 없습니다.

## 1. PlayMCP 회원 로그인 (사용자 수행)

mcp-gateway MCP 서버는 인증된 사용자만 연결할 수 있습니다.
액세스 토큰 발급을 위해 사용자에게 PlayMCP 웹사이트(https://playmcp.kakao.com) 로그인을 안내하세요.

## 2. One Time Token 및 연결 프롬프트 생성 (사용자 수행)

사용자에게 다음을 안내하세요:
1. PlayMCP 도구함(https://playmcp.kakao.com/toolbox)에 접속
2. "OpenClaw와 연결" 버튼을 눌러 연결 프롬프트 생성
3. 생성된 프롬프트(OTT 포함)를 복사해 현재 대화창에 붙여넣기

사용자가 새 프롬프트를 붙여넣으면 포함된 OTT 값을 사용해 "3. mcporter 설치"부터 재개하세요.

## 3. mcporter 설치

mcporter가 설치되어 있지 않다면 먼저 설치하세요.
컨테이너 환경에서 이 요청을 받더라도 기본 시스템 환경에 설치해야 합니다.

## 4. 서버 정의 추가

아래 커맨드를 실행해서 mcporter에 서버를 등록하세요:

```
mcporter config add mcp-gateway https://playmcp.kakao.com/mcp --auth oauth --scope home
```

이 명령으로 생성되거나 수정되는 mcporter 관련 설정은 기본 시스템 환경의 ~/.mcporter/ 에 저장되어야 합니다.

## 5. 액세스 토큰 발급

`<ONE_TIME_TOKEN>`을 제공받은 oneTimeToken 값으로 대체하여 실행하세요:

```
curl -X 'POST' 'https://playmcp.kakao.com/api/v1/auths/otts:exchange' -H 'accept: */*' -H 'Content-Type: application/json' -d '{"tokenValue":"<ONE_TIME_TOKEN>"}'
```

200 응답을 받지 못한 경우, OTT가 유효하지 않거나 만료된 상황입니다. 사용자에게 PlayMCP 웹사이트(https://playmcp.kakao.com)에서 연결 프롬프트를 새로 생성하여 다시 붙여넣어 달라고 안내하세요.

200 응답을 받은 경우, response body 는 다음 형식으로 내려옵니다. 
{
    "accessToken": {
        "tokenValue": {accessTokenValue},
        "expiresAt": {accessTokenExpiresAt},
    },
    "refreshToken": {
        "tokenValue": {refreshTokenValue},
        "expiresAt": {refreshTokenExpiresAt},
    }
}

## 6. 인증정보 설정 (~/.mcporter/credentials.json)

vault 키는 `mcp-gateway|{hash}` 형식입니다. `{hash}`는 아래 커맨드로 계산하세요:

```
printf '{"name":"mcp-gateway","url":"https://playmcp.kakao.com/mcp","command":null}' | shasum -a 256 | cut -c1-16
```

아래 json 예시를 참고하여 credentails.json 파일의 entries 에 MCP 서버 및 인증정보를 추가하세요.
- 참고1: `mcp-gateway|{hash}` 가 겹친다면 value 만 업데이트하세요.
- 참고2: credentials.json 파일이 없으면 양식에 맞게 새로 생성하세요.
- 참고3: credentials.json 파일의 백업은 필요하지 않습니다.

완성된 credentials.json 파일은 다음의 양식이어야 합니다. 중괄호 안에 표시된 값은 적절한 값으로 설정하세요.

```json
  {
    "version": 1,
    "entries": {
      "mcp-gateway|{hash}": {
        "serverName": "mcp-gateway",
        "serverUrl": "https://playmcp.kakao.com/mcp",
        "tokens": {
          "access_token": "{accessTokenValue}",
          "token_type": "Bearer",
          "refresh_token": "{refreshTokenValue}"
        },
        "clientInfo": {
          "client_id": "HElMUWdVoroTsrXxezeTSemg8gXzzCKWARb5MJux8gY"
        },
        "updatedAt": "{현재시각 ISO 형식}"
      }
    }
  }
```
credentials.json 파일은 반드시 기본 시스템 환경의 ~/.mcporter 패키지에 위치해야 합니다.

## 7. 연결 완료 및 검증

설정 완료 후 연결 상태를 확인하세요:

```
mcporter list mcp-gateway
```