# Gemini + MCP 데모 스크립트 v5: Vercel MCP Server 설정

## Vercel MCP란?

Vercel이 공식적으로 제공하는 **원격 MCP 서버**다.

### 핵심 정보

- **공식 엔드포인트**: `https://mcp.vercel.com`
- **Transport**: HTTP (원격 접근 가능)
- **인증**: OAuth 2.0
- **상태**: Production ready

### 왜 Vercel MCP를 선택했나?

1. **공식 지원**: Vercel이 직접 운영하는 서버
2. **별도 설치 불필요**: 원격 HTTP 접근
3. **Gemini 공식 지원**: 지원 클라이언트 목록에 Gemini 포함
4. **실용적인 use case**: 실제 Vercel 프로젝트 관리 가능

## 제공되는 도구 (Tools)

Vercel MCP는 두 가지 범주의 도구를 제공한다:

### 1. 공개 도구 (Public Tools)

인증 없이 누구나 사용 가능:

- **문서 검색**: Vercel 공식 문서 검색
- **기술 정보 조회**: Vercel 플랫폼 관련 정보

### 2. 인증 도구 (Authenticated Tools)

Vercel 계정 인증 후 사용 가능:

- **프로젝트 관리**: 프로젝트 목록 조회, 상세 정보
- **배포 관리**: 배포 목록, 배포 상태 확인
- **로그 분석**: 배포 로그, 에러 로그 조회
- **환경 변수 관리**: 프로젝트 환경 변수 조회

## 엔드포인트 구조

### 기본 엔드포인트

```
https://mcp.vercel.com
```

모든 Vercel 리소스에 접근 가능 (권한 내에서)

### 프로젝트 특정 엔드포인트

```
https://mcp.vercel.com/<teamSlug>/<projectSlug>
```

특정 팀/프로젝트로 범위 제한 가능

예시:
```
https://mcp.vercel.com/acme-corp/my-awesome-app
```

## MCP Protocol 플로우

### 1. Tools 목록 조회

```http
POST https://mcp.vercel.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
```

응답 예시:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search_docs",
        "description": "Search Vercel documentation",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Search query"
            }
          },
          "required": ["query"]
        }
      },
      {
        "name": "list_projects",
        "description": "List Vercel projects",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      }
      // ... more tools
    ]
  }
}
```

### 2. Tool 실행

```http
POST https://mcp.vercel.com
Content-Type: application/json
Authorization: Bearer <vercel_token>

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_docs",
    "arguments": {
      "query": "deployment logs"
    }
  },
  "id": 2
}
```

## 인증 방식

### OAuth 2.0 플로우

Vercel MCP는 OAuth 2.0을 사용한다:

1. **Authorization URL**: 사용자를 Vercel 로그인으로 리다이렉트
2. **Callback**: 인증 코드 수신
3. **Token Exchange**: Access token 획득
4. **API 호출**: Bearer token으로 인증

### 개발 환경에서는?

개발/테스트 목적으로는 **Vercel Access Token**을 직접 사용할 수 있다:

1. Vercel Dashboard → Settings → Tokens
2. New Token 생성
3. HTTP Header에 포함: `Authorization: Bearer <token>`

## 지원하는 클라이언트

Vercel MCP는 다양한 AI 클라이언트를 지원한다:

- Claude Code
- ChatGPT
- Cursor
- VS Code Copilot
- Devin
- Raycast
- Goose
- Windsurf
- **Gemini** ✓

**중요**: Gemini가 공식 지원 목록에 포함되어 있다!

## 우리의 접근 방식

Vercel MCP를 Claude나 다른 클라이언트처럼 직접 사용하는 대신, **Gemini에서 호출 가능하도록 브릿지를 만든다**:

```
┌─────────────┐
│   Gemini    │
│   Model     │
└──────┬──────┘
       │
       │ Function Call
       │
┌──────▼──────────┐
│  Our Adapter    │ ◄── v6에서 구현
│  (Node.js)      │
└──────┬──────────┘
       │
       │ HTTP Request
       │ (JSON-RPC 2.0)
       │
┌──────▼──────────┐
│  Vercel MCP     │
│  https://mcp.   │
│  vercel.com     │
└─────────────────┘
```

## 보안 고려사항

Vercel MCP 공식 문서에서 강조하는 보안 사항:

### 1. 공식 엔드포인트 확인
- 항상 `https://mcp.vercel.com` 사용
- 의심스러운 도메인 주의

### 2. 데이터 보호
- 민감한 정보 노출 주의
- Access token 안전하게 관리

### 3. Prompt Injection 인식
- 악의적인 프롬프트로 의도하지 않은 동작 방지

### 4. 인적 승인 (Human in the Loop)
- 중요한 작업은 사용자 확인 후 실행

## 환경 설정

### 필요한 정보

```bash
# .env
VERCEL_TOKEN=your_vercel_access_token
MCP_ENDPOINT=https://mcp.vercel.com
```

### Vercel Token 생성 방법

1. https://vercel.com/account/tokens 접속
2. "Create Token" 클릭
3. Token name 입력 (예: "Gemini MCP Demo")
4. Scope 선택 (필요한 권한만)
5. 생성된 token을 안전하게 보관

## 테스트 시나리오

### 시나리오 1: 공개 도구 테스트 (인증 불필요)

```bash
curl -X POST https://mcp.vercel.com \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_docs",
      "arguments": {
        "query": "edge functions"
      }
    },
    "id": 1
  }'
```

### 시나리오 2: 인증 도구 테스트

```bash
curl -X POST https://mcp.vercel.com \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_projects",
      "arguments": {}
    },
    "id": 2
  }'
```

## 다음 단계

v6에서는 이제 실제로 Gemini SDK와 Vercel MCP를 연동하는 코드를 작성할 것이다.

**핵심 과제**:
1. Vercel MCP의 tools를 Gemini function declarations로 변환
2. Gemini의 function call을 MCP JSON-RPC 요청으로 변환
3. MCP 응답을 Gemini이 이해할 수 있는 형태로 변환

---

**작성일**: 2025-11-26
**참고**:
- [Vercel MCP 공식 문서](https://vercel.com/docs/mcp/vercel-mcp)
- [MCP Specification](https://modelcontextprotocol.io)