# Máy chủ MCP BlockVectra: công cụ RPC blockchain và tài liệu cho AI Agent > Source: https://docs.blockvectra.com/vi/guides/mcp-server/ 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](https://docs.blockvectra.com/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](https://docs.blockvectra.com/vi/guides/ai-agents/). ## Công cụ | Công cụ | Chức năng | API key | Loại truy cập | | --- | --- | --- | --- | | `read_doc` | Đọc một trang tài liệu dưới dạng Markdown. | Không cần | Chỉ đọc | | `search_docs` | Tìm trong tiêu đề, đường dẫn và tóm tắt của tài liệu. | Không cần | Chỉ đọc | | `list_chains` | Liệt kê các chuỗi được hỗ trợ, tham số và chính sách phương thức (GET /v1/chains). | Không cần | Chỉ đọc | | `get_status` | Đọc trạng thái trực tiếp của dịch vụ và các chuỗi (GET /v1/status). | Không cần | Chỉ đọc | | `get_pricing` | Đọc trọng số Compute Unit, tham số gói miễn phí và giá trị mặc định của key (GET /v1/plans). | Không cần | Chỉ đọc | | `estimate_usage` | Ước tính Compute Unit và chi phí cho một hoặc nhiều phương thức. | Không cần | Chỉ đọc | | `how_to_get_api_key` | Trả về các bước lấy API key và cách xác thực yêu cầu. | Không cần | Chỉ đọc | | `get_method_info` | Cho biết phương thức khả dụng trên chuỗi nào, trọng số CU và giá. | Không cần | Chỉ đọc | | `explain_error` | Tra cứu ý nghĩa của lỗi, cách tính phí, khả năng thử lại và cách khôi phục. | Không cần | Chỉ đọc | | `list_docs` | Liệt kê mọi trang tài liệu kèm đường dẫn và tiêu đề. | Không cần | Chỉ đọc | | `rpc_call` | Chạy một phương thức JSON-RPC chỉ đọc trên chuỗi được hỗ trợ. | Tùy chọn: không cần key chỉ với các phương thức trong public.methods của chuỗi | Chỉ đọc | | `data_api_get` | Gửi yêu cầu GET tới Data API của chuỗi được hỗ trợ. | Bắt buộc (header x-api-key) | Chỉ đọc | | `get_account` | Đọc số dư tài khoản, CU và giới hạn tốc độ (GET /v1/account). | Bắt buộc (header x-api-key) | Chỉ đọc | | `get_deposit_address` | Đọc địa chỉ nạp tiền của tài khoản, các mạng đang mở và token. | Bắt buộc (header x-api-key) | Chỉ đọc | | `send_raw_transaction` | Phát sóng giao dịch thô đã được ký (eth_sendRawTransaction). | Tùy chọn: không cần key chỉ với các phương thức trong public.methods của chuỗi | Phát sóng giao dịch đã ký | 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](https://docs.blockvectra.com/vi/guides/programmatic-signup/?ref=docs-mcp-server). ## 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: ```bash 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: ```bash 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): ```json { "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`): ```bash 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](https://code.claude.com/docs/en/mcp). ### Cursor Thêm máy chủ vào cấu hình MCP của Cursor: ```json { "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"}`): ```text 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: ```json { "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](https://cursor.com/docs/context/mcp) và [liên kết cài đặt của Cursor](https://cursor.com/docs/context/mcp/install-links). ### 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"`: ```json { "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`: ```json { "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](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) và [tham chiếu cấu hình MCP của VS Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration). ### Codex Thêm máy chủ bằng OpenAI Codex CLI: ```bash codex mcp add blockvectra --url https://docs.blockvectra.com/mcp ``` Trong `config.toml`, cấu hình URL máy chủ: ```toml [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`: ```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: ```toml [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](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). ### Gemini CLI Trong cấu hình Gemini CLI, thêm máy chủ dưới `mcpServers` dùng `httpUrl` cho Streamable HTTP: ```json { "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: ```json { "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](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md). ### OpenAI Responses API Khi gọi OpenAI Responses API, truyền máy chủ MCP trong mảng `tools` với `type: "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": "", "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ụ: ```json { "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](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) và [tham chiếu OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create). ### Windsurf Trong Windsurf, cấu hình máy chủ dưới `mcpServers` dùng trường `serverUrl`: ```json { "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: ```json { "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](https://docs.devin.ai/desktop/cascade/mcp). ### 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: ```text 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](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). ### 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: ```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 ``` 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: ```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":[]}}}' ``` 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: ```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":{}}}' ``` 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](https://docs.blockvectra.com/vi/guides/programmatic-signup/?ref=docs-mcp-server), 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](https://docs.blockvectra.com/vi/errors/) để 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](https://docs.blockvectra.com/vi/guides/ai-agents/): 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](https://docs.blockvectra.com/vi/guides/programmatic-signup/?ref=docs-mcp-server): tạo API key bằng chữ ký ví, không cần trình duyệt. * [Công thức framework Agent](https://docs.blockvectra.com/vi/guides/agent-frameworks/): ElizaOS, viem, wagmi và Coinbase AgentKit. * [Mã lỗi](https://docs.blockvectra.com/vi/errors/): mọi lỗi cùng quy tắc tính phí và thử lại.