Máy chủ MCP BlockVectra: công cụ RPC blockchain và tài liệu cho AI Agent

Máy chủ MCP BlockVectra tại https://docs.blockvectra.com/mcp cung cấp cho nhà phát triển và AI Agent 15 công cụ cho lệnh gọi RPC blockchain, trạng thái chuỗi, giá và tài liệu. Kết nối không cần API key: 10 công cụ không bao giờ cần key; các công cụ còn lại dùng x-api-key từ header của client. Cài đặt bằng một dòng: claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp

Endpoint là endpoint MCP (HTTP POST nhận JSON-RPC 2.0; GET trả về 405), phục vụ qua MCP Streamable HTTP và không trạng thái. Về các tệp HTTP, JSON công khai và luồng đăng ký xung quanh, xem Kết nối AI Agent.

Công cụ

Bảng này được tạo từ sổ đăng ký công cụ của máy chủ, nên liệt kê mọi công cụ mà tools/list trả về. Mỗi công cụ nhận các tham số và trả về các trường được mô tả trong schema tools/list của chính nó.

Bảo mật API key

Các công cụ cần key yêu cầu API key để chạy yêu cầu Data API, thao tác tài khoản hoặc các phương thức RPC ngoài những phương thức công khai của chuỗi.

• Chỉ đọc từ header: API key chỉ được đọc từ header yêu cầu HTTP của MCP client (x-api-key: rgw_... hoặc Authorization: Bearer rgw_...).
• Không bao giờ đưa key vào chat: Không bao giờ truyền API key hoặc khóa riêng tư trong tham số công cụ hay dán vào chat. Tham số công cụ và lịch sử chat đi vào log và ngữ cảnh hội thoại; việc truyền key trong tham số sẽ bị từ chối.

Nếu gọi mà không có header API key, các công cụ cần key trả về isError: true và hướng Agent tới how_to_get_api_key và hướng dẫn đăng ký bằng chương trình.

Cài đặt trong client của bạn

Bạn có thể kết nối tới máy chủ MCP tài liệu BlockVectra tại https://docs.blockvectra.com/mcp trên các môi trường phát triển và framework phổ biến.

Bắt đầu không cần API key. Kết nối tới endpoint MCP, gọi list_chains, rồi đọc quickstart bằng read_doc. Thêm API key vào header HTTP của client khi bạn cần các công cụ Data API hoặc tài khoản. Truy cập RPC không cần key tuân theo chính sách phương thức công khai của từng chuỗi.

Header x-api-key là tùy chọn. Không có API key, client có thể dùng mọi công cụ tài liệu chỉ đọc (read_doc, search_docs, list_docs), khám phá chuỗi (list_chains), trạng thái trực tiếp (get_status), ước tính giá (get_pricing, estimate_usage), giải thích lỗi (explain_error) và các phương thức được phép trên endpoint công khai. Khi dùng các công cụ cần key (rpc_call với các phương thức bị hạn chế, send_raw_transaction, data_api_get, get_account và get_deposit_address), hãy cấu hình header x-api-key bằng API key của bạn.

Claude Code

Kết nối tới máy chủ MCP bằng CLI:

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

Để thêm API key tùy chọn cho các công cụ có xác thực, truyền tùy chọn --header (hoặc -H) và tham chiếu một biến môi trường thay vì dán key. Dùng dấu nháy đơn để shell không mở rộng nó; Claude Code mở rộng ${BLOCKVECTRA_API_KEY} khi khởi động phiên:

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

Cùng cấu hình đó dưới dạng .mcp.json cấp dự án (cũng là nội dung claude mcp add --scope project ghi ra):

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

Export BLOCKVECTRA_API_KEY trong môi trường khởi chạy claude. Claude Code yêu cầu bạn phê duyệt máy chủ trong .mcp.json cấp dự án lần đầu bạn chạy claude trong thư mục đó; cho đến lúc đó claude mcp list hiển thị nó là Pending approval.

Với script và CI, truyền tệp bằng --mcp-config và cho phép các công cụ của máy chủ. Key nằm trong môi trường và MCP client tự thêm header, nên Agent không cần lệnh shell mở rộng $BLOCKVECTRA_API_KEY (kiểm tra quyền của Claude Code đã từ chối các lệnh như vậy ở chế độ không tương tác với Contains simple_expansion):

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

Khi đã đặt key, kết quả của rpc_call còn chứa cu_charged và balance_units; lệnh gọi không cần key chỉ trả về phản hồi JSON-RPC. Nếu biến chưa được đặt, client gửi nguyên văn văn bản header và máy chủ trả lời invalid_api_key (mã lỗi -32024) thay vì quay về endpoint không cần key.

Tài liệu chính thức: Tài liệu MCP của Claude Code.

Cursor

Thêm máy chủ vào cấu hình MCP của Cursor:

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

Cursor cũng hỗ trợ cài đặt một cú nhấp qua deep link dùng cấu hình mã hóa base64 eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9 (đại diện cho {"url":"https://docs.blockvectra.com/mcp"}):

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

Khi bạn cần các công cụ có xác thực (Data API hoặc quản lý tài khoản), thêm đối tượng headers với API key của bạn:

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

Dạng ${env:NAME} theo tài liệu của Cursor, nơi biến được phân giải trong url và headers; dạng này chưa được chạy thử với Cursor ở đây. Đặt tệp trong .cursor/mcp.json (dự án) hoặc ~/.cursor/mcp.json (toàn cục).

Tài liệu chính thức: Tài liệu MCP của Cursor và liên kết cài đặt của Cursor.

VS Code

Trong VS Code, cấu hình máy chủ trong .vscode/mcp.json dưới khóa cấp cao nhất servers với type: "http":

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

Khi bạn cần các công cụ có xác thực, thêm đối tượng headers:

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

Khi lưu thông tin xác thực nhạy cảm, VS Code hỗ trợ tham chiếu biến input hoặc tệp môi trường thay vì ghi cứng key. Bạn cũng có thể thêm máy chủ bằng hành động Command Palette MCP: Add Server.

Tài liệu chính thức: Tài liệu máy chủ MCP của VS Code và tham chiếu cấu hình MCP của VS Code.

Codex

Thêm máy chủ bằng OpenAI Codex CLI:

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

Trong config.toml, cấu hình URL máy chủ:

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

Khi bạn cần các công cụ có xác thực, cấu hình header yêu cầu trong config.toml:

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

Hoặc ánh xạ header từ một biến môi trường:

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

Tài liệu chính thức: Tài liệu MCP của OpenAI Codex CLI.

Gemini CLI

Trong cấu hình Gemini CLI, thêm máy chủ dưới mcpServers dùng httpUrl cho Streamable HTTP:

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

Khi bạn cần các công cụ có xác thực, thêm đối tượng headers với API key của bạn:

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

Tài liệu chính thức: Tài liệu máy chủ MCP của Gemini CLI.

OpenAI Responses API

Khi gọi OpenAI Responses API, truyền máy chủ MCP trong mảng tools với type: "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": "..."
  }'

Khi bạn cần các công cụ có xác thực, thêm trường headers vào định nghĩa công cụ:

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

Tài liệu chính thức: Hướng dẫn công cụ MCP của OpenAI và tham chiếu OpenAI Responses API.

Windsurf

Trong Windsurf, cấu hình máy chủ dưới mcpServers dùng trường serverUrl:

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

Khi bạn cần các công cụ có xác thực, thêm đối tượng headers với API key của bạn:

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

Windsurf cũng hỗ trợ tham chiếu biến môi trường, chẳng hạn "x-api-key": "${env:BLOCKVECTRA_API_KEY}".

Tài liệu chính thức: Tài liệu MCP của Windsurf.

Claude Desktop và claude.ai

Custom connector được cấu hình qua giao diện người dùng:

• claude.ai: Vào Customize > Connectors, nhấp + Add, chọn Add custom connector, và nhập URL:

  Sao chép văn bản

  https://docs.blockvectra.com/mcp

• Claude Desktop: Mở menu cài đặt tài khoản và cấu hình custom connector qua giao diện connectors.

Kết nối tới URL cho phép Claude tìm kiếm hướng dẫn, đọc tài liệu Markdown, xem các chuỗi được hỗ trợ, kiểm tra trạng thái mạng và tính ước tính giá mà không cần thông tin xác thực.

Tài liệu chính thức: Hướng dẫn custom connector của Claude.

Kiểm tra kết nối và xử lý sự cố

Trong Claude Code, claude mcp list hiển thị trạng thái của từng máy chủ. Để biết số công cụ thực sự đã được đăng ký, chạy một lần với đầu ra dạng stream và đọc sự kiện init, hoặc đọc log gỡ lỗi:

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

Kết nối hoạt động hiển thị "status": "connected" và các công cụ mcp__blockvectra-docs__* (như list_chains và rpc_call) trong sự kiện init. Trong log gỡ lỗi, tìm các dòng về blockvectra-docs như Successfully connected và Failed to fetch tools. Nếu máy chủ là connected nhưng không có công cụ nào xuất hiện, hãy đọc lý do mà log gỡ lỗi (--debug mcp) báo sau Failed to fetch tools. Để kiểm tra bản thân máy chủ có khỏe không, dùng các lệnh curl bên dưới.

Gọi endpoint MCP mà không cần client

Endpoint là JSON-RPC 2.0 qua HTTP POST, nên mọi HTTP client đều gọi được:

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":[]}}}'

Lệnh gọi đầu tiên trả về danh sách công cụ; lệnh thứ hai trả về phản hồi JSON-RPC trong result.structuredContent. Định danh chuỗi là các slug như base_mainnet; lấy chúng từ list_chains. Các công cụ cần key yêu cầu header x-api-key; lệnh gọi này đọc tài khoản của bạn với key lấy từ biến môi trường:

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":{}}}'

Nó trả về key_id, plan, balance_units, balance_cu và các giới hạn tốc độ của key trong result.structuredContent. Nếu Agent của bạn chạy lệnh qua shell có kiểm soát quyền, việc mở rộng biến đó có thể bị chặn; hãy cấu hình header trong MCP client thay thế.

Câu hỏi thường gặp

Máy chủ MCP BlockVectra có cần API key không?

Không. Kết nối không cần key, và 10 trong số 15 công cụ không bao giờ cần key. rpc_call và send_raw_transaction chạy không cần key chỉ với các phương thức trong public.methods của chuỗi (đọc bằng list_chains). data_api_get, get_account và get_deposit_address cần header x-api-key.

Máy chủ MCP có thể tạo hoặc thu hồi API key không?

Không. Không có công cụ nào tạo, liệt kê hay thu hồi API key. how_to_get_api_key chỉ trả về các bước; Agent tạo key qua HTTP bằng cách làm theo đăng ký bằng chương trình, còn con người tạo key trong console. Key không bao giờ đi qua tham số công cụ.

Agent có thể gửi giao dịch qua máy chủ MCP không?

Có thể phát sóng, không thể ký. rpc_call từ chối các phương thức ghi như eth_sendRawTransaction, eth_sendTransaction, eth_sign và personal_*. send_raw_transaction phát sóng giao dịch bạn đã ký cục bộ bằng eth_sendRawTransaction; máy chủ không bao giờ giữ hay thấy khóa riêng tư.

Điều gì xảy ra khi một lệnh gọi thất bại?

Lỗi công cụ trả về isError: true cùng lý do có cấu trúc. Dùng explain_error hoặc tham chiếu mã lỗi để xem lỗi có bị tính phí không và có nên thử lại không.

Liên quan

• Kết nối AI Agent: tệp máy đọc được, endpoint JSON công khai và quy trình chọn chuỗi.
• Đăng ký bằng chương trình: tạo API key bằng chữ ký ví, không cần trình duyệt.
• Công thức framework Agent: ElizaOS, viem, wagmi và Coinbase AgentKit.
• Mã lỗi: mọi lỗi cùng quy tắc tính phí và thử lại.