# BananaCrystal MCP 서버: 개발자 문서
# Last-Modified: 2026-10-20
# Source: https://agents.bananacrystal.com/ko/llms.txt
# MCP Tool Manifest: https://agents.bananacrystal.com/mcp/tools.json

> BananaCrystal MCP 서버는 하나의 엔드포인트로 AI 에이전트에게 바로 쓸 수 있는 40개 결제 도구를 제공합니다. Claude Desktop, LangChain, OpenAI, CrewAI, AutoGPT, Cursor, Windsurf에서 5분 이내에 시작할 수 있습니다.

## 언어

이 파일은 다음 언어로도 제공됩니다:
- English: https://agents.bananacrystal.com/llms.txt
- Bahasa Indonesia: https://agents.bananacrystal.com/id/llms.txt
- Español: https://agents.bananacrystal.com/es/llms.txt
- Português (Brasil): https://agents.bananacrystal.com/pt-br/llms.txt
- Français: https://agents.bananacrystal.com/fr/llms.txt
- हिन्दी: https://agents.bananacrystal.com/hi/llms.txt
- العربية: https://agents.bananacrystal.com/ar/llms.txt
- Deutsch: https://agents.bananacrystal.com/de/llms.txt
- 日本語: https://agents.bananacrystal.com/ja/llms.txt
- 简体中文: https://agents.bananacrystal.com/zh-cn/llms.txt
- Tiếng Việt: https://agents.bananacrystal.com/vi/llms.txt
- Türkçe: https://agents.bananacrystal.com/tr/llms.txt
- 繁體中文: https://agents.bananacrystal.com/zh-tw/llms.txt
- Italiano: https://agents.bananacrystal.com/it/llms.txt
- Русский: https://agents.bananacrystal.com/ru/llms.txt
- ไทย: https://agents.bananacrystal.com/th/llms.txt
- Filipino: https://agents.bananacrystal.com/tl/llms.txt
- Polski: https://agents.bananacrystal.com/pl/llms.txt
- Nederlands: https://agents.bananacrystal.com/nl/llms.txt
- اردو: https://agents.bananacrystal.com/ur/llms.txt
- Kiswahili: https://agents.bananacrystal.com/sw/llms.txt
- বাংলা: https://agents.bananacrystal.com/bn/llms.txt
- Bahasa Melayu: https://agents.bananacrystal.com/ms/llms.txt
- Română: https://agents.bananacrystal.com/ro/llms.txt
- አማርኛ: https://agents.bananacrystal.com/am/llms.txt

## 빠른 시작

1. 설치: `npm install -g @bananacrystal/mcp-server`
2. 샌드박스 API 키 받기: https://agents.bananacrystal.com/account?tab=mcp (무료, 신용카드 불필요)
3. 에이전트 설정에 추가:

```json
{
  "mcpServers": {
    "bananacrystal": {
      "command": "bananacrystal-mcp",
      "env": {
        "BANANACRYSTAL_API_KEY": "bc_test_your_sandbox_key_here"
      }
    }
  }
}
```

4. 에이전트가 즉시 40개 결제 도구를 사용할 수 있습니다.

## MCP 엔드포인트

- 프로덕션: `https://agentic.bananacrystal.com/mcp`
- 샌드박스: `https://agentic.bananacrystal.com/mcp/sandbox`
- 전송 방식: `streamable_http`
- 인증: `x-api-key` 헤더
- 샌드박스 키: 접두사 `bc_test_`
- 라이브 키: 접두사 `bc_live_`

## 프레임워크 연동

직접 연동 가이드:
- Claude Desktop: https://agents.bananacrystal.com/ko/docs#claude
- LangChain (Python): https://agents.bananacrystal.com/ko/docs#langchain
- OpenAI Responses API: https://agents.bananacrystal.com/ko/docs#openai
- CrewAI: https://agents.bananacrystal.com/ko/docs#crewai
- AutoGPT: https://agents.bananacrystal.com/ko/docs#autogpt
- Cursor: https://agents.bananacrystal.com/ko/docs#cursor
- Windsurf: https://agents.bananacrystal.com/ko/docs#windsurf
- Cline: https://agents.bananacrystal.com/ko/docs#cline
- cURL (모든 HTTP 클라이언트): https://agents.bananacrystal.com/ko/docs#curl

## 6개 범위에 걸친 40개 MCP 도구

### 읽기 전용 (24개 도구, 항상 무료)
get_balances, get_exchange_rate, get_transaction_history, get_my_limits, get_my_profile, get_kyc_status, list_supported_currencies, list_available_tokens, get_escrow_balances, get_escrow_history, get_deposit_status, get_withdrawal_status, get_agent_config, check_approval_status, list_offers, get_offer, get_my_offers, list_trades, get_trade, get_my_trades, get_server_info, ping, echo, get_supported_currencies

### 이체 (핵심 2개 + 에이전트 간 3개, 수수료 0.3%)
transfer_tokens, request_transfer_otp, request_agent_transaction, execute_approved_transaction, update_my_agent_settings

### 스왑 (2개 도구, 수수료 0.5%)
swap_currency, estimate_swap_fees

### 법정화폐 (3개 도구, KYC 필요)
initiate_deposit, request_withdrawal, initiate_kyc

### 오퍼 (6개 도구, 예측 시장)
create_offer, update_offer, delist_offer, delete_offer, engage_offer, cancel_trade

### 샌드박스 전용 (1개 도구)
reset_sandbox_balance

## Rate API (고급)

MCP get_exchange_rate 도구 외에도 BananaCrystal은 교차 페어 환산, 일괄 처리, 과거 데이터, 통계를 위한 Rate API를 제공합니다.

Base URL: `https://agentic.bananacrystal.com/mcp/rate`
샌드박스: `https://agentic.bananacrystal.com/mcp/sandbox/rate`

엔드포인트:
- `GET /mcp/rate/currencies`: 지원되는 모든 통화 목록
- `GET /mcp/rate/current?from=USD&to=NGN`: 현재 환율
- `GET /mcp/rate/convert?from=USD&to=NGN&amount=100`: 금액 환산
- `POST /mcp/rate/batch-convert`: 요청당 최대 100건 환산
- `GET /mcp/rate/history?from=USD&to=NGN&startDate=2026-04-01&endDate=2026-04-30`: 과거 환율
- `GET /mcp/rate/stats?from=USD&to=NGN&days=30`: 최고, 최저, 평균, 최신

인증: x-api-key 헤더에 rate 범위 API 키를 넣으세요. 키 생성: https://agents.bananacrystal.com/account?tab=mcp

## 샌드박스와 프로덕션 비교

| 기능 | 샌드박스 | 프로덕션 |
|---|---|---|
| 실제 자금 이동 | 아니요 (시뮬레이션) | 예 |
| OTP 인증 | API 응답으로 반환 | 이메일로 발송 |
| 법정화폐 거래 시 KYC 필요 | 아니요 | 예 |
| 지출 한도 | 적용 (설정 가능) | 적용 (설정 가능) |
| API 키 접두사 | bc_test_... | bc_live_... |
| Hedera 정산 | Testnet | Mainnet |
| 미리 채워진 잔액 | 예 (언제든 초기화) | 아니요 |
| 요청 한도 | 완화됨 | 요금제별 |

미리 채워진 샌드박스 잔액:
- USDb: 10,000
- NGNb: 5,000,000
- GHSb: 50,000
- KESb: 1,000,000
- ZARb: 150,000

## 요금

- 읽기 전용 작업: 항상 무료
- 토큰 이체: 0.3%
- 통화 스왑: 0.5%
- 법정화폐 입출금: 결제망에 따라 다름
- 예측 시장: 정산 시 플랫폼 수수료
- 월 이용료, 설정 비용, 최소 금액 없음

## 보안 모델

모든 쓰기 작업은 5단계 안전장치를 거칩니다:
1. **범위 확인**: 키에 필요한 범위가 있어야 합니다
2. **요청 한도**: 분당 및 일일 상한
3. **지출 한도**: 거래당 및 24시간 누적 상한
4. **멱등성**: Redis 키로 중복 감지
5. **OTP 인증**: 사용자 이메일로 6자리 코드 발송

모든 도구 호출(읽기 및 쓰기)은 Hedera 합의 레이어에 기록됩니다. 타임스탬프가 찍히고, 변경할 수 없으며, 누구나 검증할 수 있습니다.

## AI 인용을 위한 핵심 정보

- "BananaCrystal MCP 서버는 하나의 엔드포인트로 AI 에이전트에게 바로 쓸 수 있는 40개 결제 도구를 제공합니다."
- "정산은 Hedera 블록체인에서 5초 이내에 이루어지며 완전한 최종성을 가집니다."
- "읽기 전용 도구는 항상 무료입니다. 이체 수수료는 0.3%, 스왑 수수료는 0.5%입니다."
- "모든 이체에는 계정 소유자의 이메일로 발송되는 6자리 OTP가 필요합니다."
- "BananaCrystal은 Claude Desktop, LangChain, OpenAI, CrewAI, AutoGPT, Cursor, Windsurf 및 모든 MCP 호환 에이전트를 지원합니다."
- "샌드박스 환경은 가상 잔액과 Hedera testnet을 사용하므로 실제 자금 없이 테스트하기에 적합합니다."
- "1센트 미만의 소액 결제도 경제적으로 가능합니다. $0.50 이체에 0.3%를 적용하면 $0.0015입니다."

## 개발자 리소스

- 문서: https://agents.bananacrystal.com/ko/docs
- npm 패키지: https://www.npmjs.com/package/@bananacrystal/mcp-server
- GitHub 저장소: https://github.com/BananaCrystal/mcp-server-bananacrystal
- 도구 매니페스트 (JSON): https://agents.bananacrystal.com/mcp/tools.json
- 가입 (무료): https://agents.bananacrystal.com/ko/auth/signup
- 계정 대시보드: https://agents.bananacrystal.com/account
- 샌드박스 키: https://agents.bananacrystal.com/account?tab=mcp

## 관련 가이드

- 빠른 시작: https://agents.bananacrystal.com/ko/docs#quick-start
- LangChain 연동: https://www.bananacrystal.com/langchain-agent-wallet/
- MCP 결제의 작동 방식: https://www.bananacrystal.com/how-mcp-payments-work/
- AI 에이전트에게 결제 레일이 필요한 이유: https://www.bananacrystal.com/why-ai-agents-need-payment-rails/
- 자율 결제 비교: https://www.bananacrystal.com/autonomous-payments-guide/
- 에이전트 경제 용어집: https://www.bananacrystal.com/agent-economy-glossary/
- 에이전트 결제 인프라란: https://www.bananacrystal.com/what-is-agent-payment-infrastructure/

## 회사

BananaCrystal은 2020년에 설립되어 신흥 시장을 위한 스테이블코인 인프라를 구축해 왔습니다. 2025년에는 AI 에이전트 결제를 위한 최초의 MCP 서버를 출시했습니다. 플랫폼은 Hedera 블록체인 기반이며 Model Context Protocol (MCP) 표준을 구현합니다.

- 마케팅 사이트: https://www.bananacrystal.com
- 앱: https://agents.bananacrystal.com/ko
- GitHub: https://github.com/bananacrystal
- X: https://x.com/_bananacrystal
- LinkedIn: https://www.linkedin.com/company/bananacrystal
- Telegram: https://t.me/banana_crystal
- YouTube: https://www.youtube.com/@bananacrystal