# BlockVectra MCP 서버: AI 에이전트를 위한 블록체인 RPC 및 문서 도구

> Source: https://docs.blockvectra.com/ko/guides/mcp-server/

`https://docs.blockvectra.com/mcp`의 BlockVectra MCP 서버는 개발자와 AI 에이전트에게 블록체인 RPC 호출, 체인 상태, 요금 및 문서를 위한 15개의 도구를 제공합니다. 연결에는 API key가 필요하지 않습니다. 10개의 도구는 키가 전혀 필요 없고, 나머지 도구는 클라이언트 헤더의 `x-api-key`를 사용합니다. 한 줄로 설치하세요: `claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp`

엔드포인트는 [MCP 엔드포인트](https://docs.blockvectra.com/mcp)이며(JSON-RPC 2.0을 수신하는 HTTP POST, GET은 405 반환), MCP Streamable HTTP로 제공되고 상태 비저장(stateless)입니다. HTTP 파일, 공개 JSON 및 이와 연계된 가입 흐름은 [AI 에이전트 연결](https://docs.blockvectra.com/ko/guides/ai-agents/)을 참조하세요.

## 도구

| 도구 | 기능 | API key | 접근 유형 |
| --- | --- | --- | --- |
| `read_doc` | 문서 페이지를 Markdown으로 읽습니다. | 필요 없음 | 읽기 전용 |
| `search_docs` | 문서 제목, 경로, 요약을 검색합니다. | 필요 없음 | 읽기 전용 |
| `list_chains` | 지원하는 체인, 파라미터, 메서드 정책을 나열합니다 (GET /v1/chains). | 필요 없음 | 읽기 전용 |
| `get_status` | 서비스와 체인의 실시간 상태를 읽습니다 (GET /v1/status). | 필요 없음 | 읽기 전용 |
| `get_pricing` | Compute Unit 가중치, 무료 플랜 파라미터, 키 기본값을 읽습니다 (GET /v1/plans). | 필요 없음 | 읽기 전용 |
| `estimate_usage` | 하나 이상의 메서드에 대한 Compute Unit과 비용을 추정합니다. | 필요 없음 | 읽기 전용 |
| `how_to_get_api_key` | API key를 발급받는 단계와 요청 인증 방식을 반환합니다. | 필요 없음 | 읽기 전용 |
| `get_method_info` | 메서드의 체인별 제공 여부, CU 가중치, 가격을 보여 줍니다. | 필요 없음 | 읽기 전용 |
| `explain_error` | 오류의 의미, 과금 여부, 재시도 가능 여부, 복구 방법을 조회합니다. | 필요 없음 | 읽기 전용 |
| `list_docs` | 모든 문서 페이지를 경로와 제목과 함께 나열합니다. | 필요 없음 | 읽기 전용 |
| `rpc_call` | 지원하는 체인에서 읽기 전용 JSON-RPC 메서드를 실행합니다. | 선택: 키 없이는 체인의 public.methods에 있는 메서드만 사용 가능 | 읽기 전용 |
| `data_api_get` | 지원하는 체인의 Data API에 GET 요청을 보냅니다. | 필수 (x-api-key 헤더) | 읽기 전용 |
| `get_account` | 계정 잔액, CU, 속도 제한을 읽습니다 (GET /v1/account). | 필수 (x-api-key 헤더) | 읽기 전용 |
| `get_deposit_address` | 계정의 입금 주소, 열려 있는 네트워크와 토큰을 읽습니다. | 필수 (x-api-key 헤더) | 읽기 전용 |
| `send_raw_transaction` | 이미 서명된 raw 트랜잭션을 브로드캐스트합니다 (eth_sendRawTransaction). | 선택: 키 없이는 체인의 public.methods에 있는 메서드만 사용 가능 | 서명된 트랜잭션을 브로드캐스트 |

이 표는 서버의 도구 레지스트리에서 생성되므로 `tools/list`가 반환하는 모든 도구가 나열됩니다. 각 도구는 자체 `tools/list` 스키마에 설명된 인수를 받고 해당 필드를 반환합니다.

### API key 보안

키가 필요한 도구는 Data API 요청, 계정 작업 또는 체인의 퍼블릭 메서드 이외의 RPC 메서드를 실행하기 위해 API key가 필요합니다.

* **헤더에서만 엄격하게 읽기**: API key는 오직 MCP 클라이언트 HTTP 요청 헤더(`x-api-key: rgw_...` 또는 `Authorization: Bearer rgw_...`)에서만 읽힙니다.
* **채팅에 키를 절대 입력하지 마세요**: 도구 인수나 채팅창에 API key 또는 개인키를 절대 전달하지 마세요. 도구 인수와 채팅 기록은 대화 로그 및 컨텍스트에 포함되므로 인수에 키를 전달하면 거부됩니다.

API key 헤더 없이 호출되면 키가 필요한 도구는 `isError: true`를 반환하고 에이전트를 `how_to_get_api_key` 및 [프로그래밍 방식 회원가입 가이드](https://docs.blockvectra.com/ko/guides/programmatic-signup/?ref=docs-mcp-server)로 안내합니다.

## 클라이언트에 설치하기

일반적인 개발 환경 및 프레임워크 전반에서 `https://docs.blockvectra.com/mcp`의 BlockVectra 문서 MCP 서버에 연결할 수 있습니다.

API key 없이 시작하세요. MCP 엔드포인트에 연결하고 list\_chains를 호출한 다음 read\_doc으로 quickstart를 읽어보세요. Data API 또는 계정 도구가 필요할 때 클라이언트의 HTTP 헤더에 API key를 추가하세요. 키 없는 RPC 접근은 각 체인의 퍼블릭 메서드 정책을 따릅니다.

`x-api-key` 헤더는 선택 사항입니다. API key가 없어도 클라이언트는 모든 읽기 전용 문서 도구(`read_doc`, `search_docs`, `list_docs`), 체인 검색(`list_chains`), 실시간 상태(`get_status`), 요금 추정(`get_pricing`, `estimate_usage`), 오류 설명(`explain_error`) 및 퍼블릭 엔드포인트에서 허용된 메서드를 사용할 수 있습니다. 키가 필요한 도구(제한된 메서드에 대한 `rpc_call`, `send_raw_transaction`, `data_api_get`, `get_account`, `get_deposit_address`)를 사용할 때는 `x-api-key` 헤더에 API key를 구성하세요.

### Claude Code

CLI를 사용하여 MCP 서버에 연결합니다:

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp
```

인증된 도구를 위해 선택적 API key를 포함하려면 `--header`(또는 `-H`) 옵션을 전달하고 키를 붙여 넣는 대신 환경 변수를 참조하세요. 셸이 확장하지 않도록 작은따옴표를 사용하세요. Claude Code가 세션을 시작할 때 `${BLOCKVECTRA_API_KEY}`를 확장합니다:

```bash
claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header 'x-api-key: ${BLOCKVECTRA_API_KEY}'
```

프로젝트 수준의 `.mcp.json`으로 나타낸 동일한 구성입니다(`claude mcp add --scope project`가 작성하는 내용이기도 합니다):

```json
{
  "mcpServers": {
    "blockvectra-docs": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": { "x-api-key": "${BLOCKVECTRA_API_KEY}" }
    }
  }
}
```

`claude`를 시작하는 환경에서 `BLOCKVECTRA_API_KEY`를 export하세요. Claude Code는 해당 디렉터리에서 `claude`를 처음 실행할 때 프로젝트 수준 `.mcp.json` 서버를 승인하도록 요청하며, 그때까지 `claude mcp list`에는 `Pending approval`로 표시됩니다.

스크립트와 CI에서는 `--mcp-config`로 파일을 전달하고 서버의 도구를 허용하세요. 키는 환경에 그대로 두고 MCP 클라이언트가 헤더를 직접 추가하므로, 에이전트가 `$BLOCKVECTRA_API_KEY`를 확장하는 셸 명령을 실행할 필요가 없습니다(Claude Code의 권한 검사는 비대화형 모드에서 이러한 명령을 `Contains simple_expansion`으로 거부했습니다):

```bash
claude -p "Use rpc_call to run eth_blockNumber on base_mainnet" \
  --mcp-config ./mcp.json --allowedTools "mcp__blockvectra-docs__*"
```

키가 설정되어 있으면 `rpc_call` 결과에 `cu_charged`와 `balance_units`도 포함되며, 키 없는 호출은 JSON-RPC 응답만 반환합니다. 변수가 설정되어 있지 않으면 클라이언트는 헤더 텍스트를 그대로 전송하고 서버는 키 없는 엔드포인트로 대체하는 대신 `invalid_api_key`(오류 코드 `-32024`)로 응답합니다.

공식 문서: [Claude Code MCP 문서](https://code.claude.com/docs/en/mcp).

### Cursor

Cursor의 MCP 구성에 서버를 추가합니다:

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

Cursor는 base64로 인코딩된 구성 `eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9`(`{"url":"https://docs.blockvectra.com/mcp"}`를 나타냄)을 사용하는 딥 링크를 통한 원클릭 설치도 지원합니다:

```text
cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9
```

인증된 도구(Data API 또는 계정 관리)가 필요한 경우 API key가 포함된 `headers` 객체를 추가하세요:

```json
{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "${env:BLOCKVECTRA_API_KEY}"
      }
    }
  }
}
```

`${env:NAME}` 형식은 `url`과 `headers`의 변수를 확인(resolve)하는 Cursor 문서를 따른 것이며, 이 형식은 여기서 Cursor에 대해 실행해 보지 않았습니다. 파일은 `.cursor/mcp.json`(프로젝트) 또는 `~/.cursor/mcp.json`(전역)에 두세요.

공식 문서: [Cursor MCP 문서](https://cursor.com/docs/context/mcp) 및 [Cursor 설치 링크](https://cursor.com/docs/context/mcp/install-links).

### VS Code

VS Code에서는 `type: "http"`를 사용하여 최상위 `servers` 키 아래의 `.vscode/mcp.json`에 서버를 구성합니다:

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

인증된 도구가 필요한 경우 `headers` 객체를 추가하세요:

```json
{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

민감한 자격 증명을 저장할 때 VS Code는 키를 하드코딩하는 대신 입력 변수나 환경 파일을 참조하는 것을 지원합니다. 명령 팔레트 작업 `MCP: Add Server`를 사용하여 서버를 추가할 수도 있습니다.

공식 문서: [VS Code MCP 서버 문서](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) 및 [VS Code MCP 구성 레퍼런스](https://code.visualstudio.com/docs/agents/reference/mcp-configuration).

### Codex

OpenAI Codex CLI를 사용하여 서버를 추가합니다:

```bash
codex mcp add blockvectra --url https://docs.blockvectra.com/mcp
```

`config.toml`에서 서버 URL을 구성합니다:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
```

인증된 도구가 필요한 경우 `config.toml`에 요청 헤더를 구성하세요:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }
```

또는 환경 변수에서 헤더를 매핑합니다:

```toml
[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }
```

공식 문서: [OpenAI Codex CLI MCP 문서](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

### Gemini CLI

Gemini CLI 구성에서 Streamable HTTP용 `httpUrl`을 사용하여 `mcpServers` 아래에 서버를 추가합니다:

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

인증된 도구가 필요한 경우 API key가 포함된 `headers` 객체를 추가하세요:

```json
{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

공식 문서: [Gemini CLI MCP 서버 문서](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md).

### OpenAI Responses API

OpenAI Responses API를 호출할 때 `type: "mcp"`와 함께 `tools` 배열에 MCP 서버를 전달합니다:

```bash
OPENAI_API_BASE="https://api.openai.com/v1"
curl "$OPENAI_API_BASE/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "blockvectra",
      "server_url": "https://docs.blockvectra.com/mcp",
      "require_approval": "never"
    }],
    "input": "..."
  }'
```

인증된 도구가 필요한 경우 도구 정의에 `headers` 필드를 포함하세요:

```json
{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}
```

공식 문서: [OpenAI MCP 도구 가이드](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) 및 [OpenAI Responses API 레퍼런스](https://developers.openai.com/api/reference/resources/responses/methods/create).

### Windsurf

Windsurf에서는 `serverUrl` 필드를 사용하여 `mcpServers` 아래에 서버를 구성합니다:

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}
```

인증된 도구가 필요한 경우 API key가 포함된 `headers` 객체를 추가하세요:

```json
{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}
```

Windsurf는 `"x-api-key": "${env:BLOCKVECTRA_API_KEY}"`와 같이 환경 변수를 참조하는 것도 지원합니다.

공식 문서: [Windsurf MCP 문서](https://docs.devin.ai/desktop/cascade/mcp).

### Claude Desktop 및 claude.ai

커스텀 커넥터는 사용자 인터페이스를 통해 구성됩니다:

* **claude.ai**: **Customize** > **Connectors**로 이동하여 **+ Add**를 클릭하고, **Add custom connector**를 선택한 후 URL을 입력합니다:
  ```text
  https://docs.blockvectra.com/mcp
  ```
* **Claude Desktop**: 계정 설정 메뉴를 열고 커넥터 인터페이스를 통해 커스텀 커넥터를 구성합니다.

해당 URL에 연결하면 Claude가 인증 정보 없이 가이드를 검색하고, Markdown 문서를 읽고, 지원 체인을 검사하고, 네트워크 상태를 확인하며, 요금 추정치를 계산할 수 있습니다.

공식 문서: [Claude 커스텀 커넥터 가이드](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp).

### 연결 확인 및 문제 해결

Claude Code에서 `claude mcp list`는 각 서버의 상태를 보여줍니다. 실제로 등록된 도구의 수를 확인하려면 스트림 출력으로 한 번 실행하여 `init` 이벤트를 읽거나 디버그 로그를 읽으세요:

```bash
claude -p "say ok" --mcp-config ./mcp.json --output-format stream-json --verbose
claude -p "say ok" --mcp-config ./mcp.json --debug mcp --debug-file mcp-debug.log
```

정상적으로 연결되면 `init` 이벤트에 `"status": "connected"`와 `mcp__blockvectra-docs__*` 도구(`list_chains`, `rpc_call` 등)가 표시됩니다. 디버그 로그에서는 `Successfully connected`, `Failed to fetch tools`와 같은 `blockvectra-docs` 관련 줄을 찾아보세요. 서버가 `connected`인데 도구가 나타나지 않으면 `Failed to fetch tools` 뒤에 디버그 로그(`--debug mcp`)가 보고하는 이유를 읽어보세요. 서버 자체가 정상인지 확인하려면 아래 curl 호출을 사용하세요.

### 클라이언트 없이 MCP 엔드포인트 호출하기

엔드포인트는 HTTP POST 위의 JSON-RPC 2.0이므로 어떤 HTTP 클라이언트로도 호출할 수 있습니다:

```bash
curl -s https://docs.blockvectra.com/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://docs.blockvectra.com/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"rpc_call","arguments":{"chain":"base_mainnet","method":"eth_blockNumber","params":[]}}}'
```

첫 번째 호출은 도구 목록을 반환하고, 두 번째 호출은 `result.structuredContent`에 JSON-RPC 응답을 반환합니다. 체인 식별자는 `base_mainnet` 같은 슬러그이며 `list_chains`에서 얻을 수 있습니다. 키가 필요한 도구에는 `x-api-key` 헤더가 필요합니다. 다음 호출은 환경 변수의 키로 계정을 조회합니다:

```bash
curl -s https://docs.blockvectra.com/mcp -H 'content-type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'
```

이 호출은 `result.structuredContent`에 `key_id`, `plan`, `balance_units`, `balance_cu` 및 키의 속도 제한을 반환합니다. 에이전트가 권한 제어가 있는 셸을 통해 명령을 실행하는 경우 이러한 변수 확장이 차단될 수 있으므로, 대신 MCP 클라이언트에서 헤더를 구성하세요.

## FAQ

### BlockVectra MCP 서버에는 API key가 필요한가요?

아니요. 연결에는 키가 필요 없으며, 15개의 도구 중 10개는 키가 전혀 필요하지 않습니다. `rpc_call`과 `send_raw_transaction`은 체인의 `public.methods`에 있는 메서드에 대해서만 키 없이 실행됩니다(`list_chains`로 확인하세요). `data_api_get`, `get_account`, `get_deposit_address`에는 `x-api-key` 헤더가 필요합니다.

### MCP 서버로 API key를 생성하거나 폐기할 수 있나요?

아니요. API key를 생성, 조회 또는 폐기하는 도구는 없습니다. `how_to_get_api_key`는 단계만 반환하며, 에이전트는 [프로그래밍 방식 회원가입](https://docs.blockvectra.com/ko/guides/programmatic-signup/?ref=docs-mcp-server)을 따라 HTTP로 키를 생성하고, 사람은 콘솔에서 생성합니다. 키는 도구 인수를 통해 전달되지 않습니다.

### 에이전트가 MCP 서버를 통해 트랜잭션을 보낼 수 있나요?

브로드캐스트는 할 수 있지만 서명은 할 수 없습니다. `rpc_call`은 `eth_sendRawTransaction`, `eth_sendTransaction`, `eth_sign`, `personal_*` 같은 쓰기 메서드를 거부합니다. `send_raw_transaction`은 로컬에서 이미 서명한 트랜잭션을 `eth_sendRawTransaction`으로 브로드캐스트하며, 서버는 개인키를 보관하거나 보지 않습니다.

### 호출이 실패하면 어떻게 되나요?

도구 오류는 구조화된 사유와 함께 `isError: true`를 반환합니다. `explain_error` 또는 [오류 코드 레퍼런스](https://docs.blockvectra.com/ko/errors/)를 사용하여 실패가 과금되는지, 재시도해야 하는지 확인하세요.

## 관련 문서

* [AI 에이전트 연결](https://docs.blockvectra.com/ko/guides/ai-agents/): 기계 판독 가능한 파일, 공개 JSON 엔드포인트 및 체인 선택 워크플로.
* [프로그래밍 방식 회원가입](https://docs.blockvectra.com/ko/guides/programmatic-signup/?ref=docs-mcp-server): 브라우저 없이 지갑 서명으로 API key를 생성합니다.
* [에이전트 프레임워크 레시피](https://docs.blockvectra.com/ko/guides/agent-frameworks/): ElizaOS, viem, wagmi, Coinbase AgentKit.
* [오류 코드](https://docs.blockvectra.com/ko/errors/): 과금 및 재시도 규칙이 포함된 모든 오류.