# MCP · AI 도구에서 blockwallets를 바로 쓰세요

> blockwallets 원격 MCP 서버: Claude, ChatGPT, Cursor, Codex에서 연동 문서를 검색하고, 테스트 청구서를 만들고, 주문과 잔액을 확인하세요. 자금을 밖으로 보낼 수 있는 도구는 하나도 없습니다.

Claude, ChatGPT, Cursor, Codex가 문서를 읽고, 테스트 청구서를 만들고, 주문을 확인하게 하세요. 결제 받기와 데이터 읽기만 할 수 있고, 돈을 밖으로 보낼 수는 없습니다.

## 주소 두 개

- `https://blockwallets.io/mcp` (로그인 필요): OAuth 로그인 또는 관리 화면에서 만든 MCP 토큰(Bearer). 모든 도구.
- `https://blockwallets.io/mcp/public` (로그인 불필요): 공개 도구만: 문서, 네트워크, 요금, 서명 설명, 연동 체크리스트.

## 한마디로 AI 안에서 연동하고, 디버깅하고, 장부를 확인합니다.

- 연동 코드를 쓰는 동안 AI가 저희 문서와 서명 규칙을 직접 읽습니다. 복사해서 붙여 넣을 필요가 없습니다.
- 테스트 토큰으로 AI가 테스트 청구서를 만들고, 당신이 결제를 시뮬레이션하면, AI가 처음부터 끝까지 상태를 확인합니다.
- 평소에는 “어제 얼마 받았어?”, “order_1042 결제됐어?”라고 물으면 답을 받을 수 있습니다.

## 코드 한 조각을 도구에 붙여 넣으세요.

토큰은 관리 화면 “개발자 › AI 도구(MCP)”에서 만듭니다. 토큰은 한 번만 표시됩니다. 테스트 토큰으로 시작하세요.

### Claude Code

토큰을 쓰는 방법입니다. --header를 빼고 Claude Code 안에서 /mcp를 실행하면 OAuth로 로그인할 수 있습니다.

```bash
claude mcp add --transport http blockwallets https://blockwallets.io/mcp \
  --header "Authorization: Bearer bw_mcp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Claude Code · 문서 도구만 (로그인 없이)

```bash
claude mcp add --transport http blockwallets-docs https://blockwallets.io/mcp/public
```

### Cursor · ~/.cursor/mcp.json

```json
{
  "mcpServers": {
    "blockwallets": {
      "url": "https://blockwallets.io/mcp",
      "headers": {
        "Authorization": "Bearer bw_mcp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Windsurf · ~/.codeium/windsurf/mcp_config.json

```json
{
  "mcpServers": {
    "blockwallets": {
      "serverUrl": "https://blockwallets.io/mcp",
      "headers": {
        "Authorization": "Bearer bw_mcp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Codex · ~/.codex/config.toml

토큰은 환경 변수 BLOCKWALLETS_MCP_TOKEN에 넣으세요. HTTP MCP를 지원하는 최신 Codex가 필요합니다.

```toml
[mcp_servers.blockwallets]
url = "https://blockwallets.io/mcp"
bearer_token_env_var = "BLOCKWALLETS_MCP_TOKEN"
```

## Claude와 ChatGPT는 로그인만 하면 됩니다.

### Claude (웹 / 데스크톱)

1. 설정 → 커넥터 → 사용자 지정 커넥터 추가
2. 이름은 blockwallets, URL은 https://blockwallets.io/mcp
3. 연결을 누르고 열리는 페이지에서 blockwallets 관리 화면에 로그인
4. 동의 페이지에서 테스트 또는 실서비스 모드와 청구서 생성 허용 여부를 고른 뒤 허용을 누르기

### ChatGPT

1. 설정 → 앱 및 커넥터 → 고급에서 개발자 모드 켜기
2. URL https://blockwallets.io/mcp, OAuth 인증으로 커넥터 만들기
3. blockwallets 관리 화면에 로그인
4. 동의 페이지에서 모드와 권한을 고르고 허용을 누르기

로그인하고 싶지 않다면 https://blockwallets.io/mcp/public을 쓰세요. 공개 문서 도구만 쓸 수 있습니다.

## 도구 11개, 어느 것도 돈을 밖으로 보내지 못합니다.

| 도구 | 하는 일 | 권한 |
|---|---|---|
| `search_docs` | 연동 문서를 검색해 관련 섹션과 링크를 돌려줍니다 | 공개 |
| `get_doc` | 문서의 한 섹션을 Markdown으로 읽습니다 | 공개 |
| `list_networks` | 코인과 네트워크, 컨펌 수, 최소 금액 | 공개 |
| `get_pricing` | 수수료와 거래액 구간 | 공개 |
| `explain_signature` | 서명 계산 과정을 단계별로 보여 줍니다 (API key는 받지 않음) | 공개 |
| `integration_checklist` | 기술 스택에 맞는 연동 단계와 인수 체크리스트 | 공개 |
| `create_payment` | 청구서를 만들고 결제 페이지를 돌려줍니다 (order_id 기준 멱등) | payments:create |
| `create_payment_link` | 결제 링크와 QR 코드를 만듭니다 | payments:create |
| `get_payment` | order_id 또는 uuid로 청구서 한 건을 읽습니다 | read |
| `list_payments` | 상태와 날짜로 청구서 목록을 봅니다 | read |
| `get_balance` | 실서비스 잔액을 읽습니다 (읽기 전용, 출금 불가) | read |

## 받기만 합니다. 보내지 않습니다.

- **돈을 내보내는 도구는 없습니다**: 출금, 지급, 환불, 출금 주소, 콜백 URL, 키 변경은 MCP에 없고 해당 권한도 없습니다. 관리 화면에서 당신만 할 수 있습니다.
- **테스트 모드로 시작하세요**: 테스트 자격 증명은 테스트넷에서만 청구서를 만들고 테스트 데이터만 봅니다. 실제 돈은 없습니다.
- **실서비스는 읽기 전용으로**: 실서비스 자격 증명은 실제 주문과 잔액을 봅니다. 청구서를 만들 필요가 없다면 읽기만 허용하세요. 2단계 인증을 켠 계정은 실서비스 자격 증명을 만들 때 코드가 필요하며, 매번 이메일로 알려 드립니다.
- **언제든 취소**: 토큰과 OAuth 승인은 관리 화면의 같은 목록에 있습니다. 취소하면 해당 토큰은 즉시 작동을 멈춥니다.
- **해시만 저장**: 토큰과 코드는 sha256으로만 저장하고 토큰은 한 번만 보여 드립니다. 가맹점의 모든 호출은 감사 기록에 남고, 자격 증명마다 분당 60회로 제한됩니다.

## 자주 묻는 질문

### MCP가 뭔가요?

Model Context Protocol, AI 도구가 외부 서비스를 호출하기 위한 개방형 표준입니다. 연결하면 Claude, ChatGPT, Cursor 등이 blockwallets 도구를 직접 호출할 수 있습니다.

### AI가 이걸로 제 돈을 가져갈 수 있나요?

아니요. 출금, 지급, 환불, 주소나 키 변경을 하는 도구가 없고, 그런 권한도 존재하지 않습니다.

### 테스트와 실서비스는 어떻게 다른가요?

테스트 모드는 공개 테스트넷에서 테스트 청구서와 데이터로 동작하고, 실서비스는 실제 계정입니다. 먼저 테스트 모드에서 흐름을 완성하세요.

### Cursor도 OAuth로 로그인할 수 있나요?

지금은 Cursor에서 관리 화면 토큰을 쓰세요. OAuth는 Claude, ChatGPT, Claude Code처럼 https나 루프백으로 리디렉션하는 클라이언트에서 동작합니다.

### 접근 권한은 어떻게 취소하나요?

관리 화면 “개발자 › AI 도구(MCP)”에서 해당 토큰이나 승인을 찾아 취소하면 즉시 적용됩니다.

OAuth metadata: https://blockwallets.io/.well-known/oauth-protected-resource · https://blockwallets.io/.well-known/oauth-authorization-server