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

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 엔드포인트이며(JSON-RPC 2.0을 수신하는 HTTP POST, GET은 405 반환), MCP Streamable HTTP로 제공되고 상태 비저장(stateless)입니다. HTTP 파일, 공개 JSON 및 이와 연계된 가입 흐름은 AI 에이전트 연결을 참조하세요.

도구

이 표는 서버의 도구 레지스트리에서 생성되므로 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/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 서버에 연결합니다:

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

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

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가 작성하는 내용이기도 합니다):

{
  "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으로 거부했습니다):

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 문서.

Cursor

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

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

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

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

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

{
  "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 문서 및 Cursor 설치 링크.

VS Code

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

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

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

{
  "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 서버 문서 및 VS Code MCP 구성 레퍼런스.

Codex

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

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

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

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

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

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

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

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

공식 문서: OpenAI Codex CLI MCP 문서.

Gemini CLI

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

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

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

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

공식 문서: Gemini CLI MCP 서버 문서.

OpenAI Responses API

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

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 필드를 포함하세요:

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

공식 문서: OpenAI MCP 도구 가이드 및 OpenAI Responses API 레퍼런스.

Windsurf

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

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

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

{
  "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 문서.

Claude Desktop 및 claude.ai

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

• claude.ai: Customize > Connectors로 이동하여 + Add를 클릭하고, Add custom connector를 선택한 후 URL을 입력합니다:

  텍스트 복사

  https://docs.blockvectra.com/mcp

• Claude Desktop: 계정 설정 메뉴를 열고 커넥터 인터페이스를 통해 커스텀 커넥터를 구성합니다.

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

공식 문서: Claude 커스텀 커넥터 가이드.

연결 확인 및 문제 해결

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

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 클라이언트로도 호출할 수 있습니다:

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 헤더가 필요합니다. 다음 호출은 환경 변수의 키로 계정을 조회합니다:

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는 단계만 반환하며, 에이전트는 프로그래밍 방식 회원가입을 따라 HTTP로 키를 생성하고, 사람은 콘솔에서 생성합니다. 키는 도구 인수를 통해 전달되지 않습니다.

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

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

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

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

관련 문서

• AI 에이전트 연결: 기계 판독 가능한 파일, 공개 JSON 엔드포인트 및 체인 선택 워크플로.
• 프로그래밍 방식 회원가입: 브라우저 없이 지갑 서명으로 API key를 생성합니다.
• 에이전트 프레임워크 레시피: ElizaOS, viem, wagmi, Coinbase AgentKit.
• 오류 코드: 과금 및 재시도 규칙이 포함된 모든 오류.