# BlockVectra MCP 伺服器：給 AI Agent 的區塊鏈 RPC 與文件工具

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

位於 `https://docs.blockvectra.com/mcp` 的 BlockVectra MCP 伺服器，為開發者與 AI Agent 提供 15 個區塊鏈 RPC 呼叫、鏈狀態、定價與文件工具。連線不需要 API key：其中 10 個工具永遠不需要 key，其餘工具使用用戶端標頭中的 `x-api-key`。一行安裝：`claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp`

端點為 [MCP 端點](https://docs.blockvectra.com/mcp)（HTTP POST 接收 JSON-RPC 2.0；GET 回傳 405），採用 MCP Streamable HTTP 傳輸且無狀態。關於 HTTP 檔案、公開 JSON 及其周邊的註冊流程，請參閱[連線 AI Agent](https://docs.blockvectra.com/zh-hant/guides/ai-agents/)。

## 工具

| 工具 | 用途 | API key | 存取類型 |
| --- | --- | --- | --- |
| `read_doc` | 讀取文件頁的 Markdown 原文。 | 不需要 | 唯讀 |
| `search_docs` | 依關鍵字搜尋文件標題、路徑與摘要。 | 不需要 | 唯讀 |
| `list_chains` | 列出支援的鏈、參數與方法政策（GET /v1/chains）。 | 不需要 | 唯讀 |
| `get_status` | 讀取即時服務與鏈狀態（GET /v1/status）。 | 不需要 | 唯讀 |
| `get_pricing` | 讀取計算單位權重、免費額度參數與 key 預設限額（GET /v1/plans）。 | 不需要 | 唯讀 |
| `estimate_usage` | 估算一個或多個方法的計算單位與費用。 | 不需要 | 唯讀 |
| `how_to_get_api_key` | 回傳取得 API key 的步驟與請求驗證寫法。 | 不需要 | 唯讀 |
| `get_method_info` | 查看方法的可用鏈、CU 權重與價格。 | 不需要 | 唯讀 |
| `explain_error` | 查詢錯誤的含義、是否計費、能否重試與復原方式。 | 不需要 | 唯讀 |
| `list_docs` | 列出全部文件頁的路徑與標題。 | 不需要 | 唯讀 |
| `rpc_call` | 在支援的鏈上執行唯讀 JSON-RPC 方法。 | 選用：免 key 僅限該鏈 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` | 廣播已簽署的原始交易（eth_sendRawTransaction）。 | 選用：免 key 僅限該鏈 public.methods 內的方法 | 廣播已簽署交易 |

此表由伺服器的工具登錄表產生，因此列出 `tools/list` 回傳的每一個工具。每個工具接受的參數與回傳的欄位，以其自身 `tools/list` 結構描述為準。

### API key 安全

需要 key 的工具需要 API key，才能執行 Data API 請求、帳戶操作，或鏈上公開方法以外的 RPC 方法。

* **僅從標頭讀取**：API key 只會從 MCP 用戶端的 HTTP 請求標頭讀取（`x-api-key: rgw_...` 或 `Authorization: Bearer rgw_...`）。
* **絕不放進對話**：絕不要把 API key 或私鑰放在工具參數中，也不要貼到對話裡。工具參數與對話歷史會進入對話記錄與上下文；在參數中傳入 key 會被拒絕。

若呼叫時沒有 API key 標頭，需要 key 的工具會回傳 `isError: true`，並引導 agent 使用 `how_to_get_api_key` 與[程式化建立帳戶指南](https://docs.blockvectra.com/zh-hant/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。免 key 的 RPC 存取遵循各鏈的公開方法政策。

`x-api-key` 標頭是選用的。沒有 API key 時，用戶端可以使用所有唯讀文件工具（`read_doc`、`search_docs`、`list_docs`）、鏈探索（`list_chains`）、即時狀態（`get_status`）、定價估算（`get_pricing`、`estimate_usage`）、錯誤說明（`explain_error`），以及公開端點允許的方法。使用需要 key 的工具（受限方法的 `rpc_call`、`send_raw_transaction`、`data_api_get`、`get_account` 與 `get_deposit_address`）時，請把 API key 設定在 `x-api-key` 標頭中。

### Claude Code

使用 CLI 連線到 MCP 伺服器：

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

若要加入選用的 API key 以使用需要認證的工具，請傳入 `--header`（或 `-H`）選項，並引用環境變數而不是貼上 key。請使用單引號，避免 shell 展開；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`。第一次在該目錄執行 `claude` 時，Claude Code 會請你核准專案層級 `.mcp.json` 中的伺服器；在此之前，`claude mcp list` 會顯示為 `Pending approval`。

對於指令碼與 CI，請用 `--mcp-config` 傳入該檔案，並允許該伺服器的工具。key 留在環境變數中，由 MCP 用戶端自行加上標頭，因此 agent 不需要執行展開 `$BLOCKVECTRA_API_KEY` 的 shell 命令（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__*"
```

設定 key 後，`rpc_call` 的結果還會包含 `cu_charged` 與 `balance_units`；免 key 呼叫只回傳 JSON-RPC 回應。若該變數未設定，用戶端會原樣送出字面標頭文字，伺服器回應 `invalid_api_key`（錯誤碼 `-32024`），而不是退回免 key 端點。

官方文件：[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}` 形式依照 Cursor 文件，Cursor 會解析 `url` 與 `headers` 中的變數；這裡尚未在 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 中，於 `.vscode/mcp.json` 的頂層 `servers` 鍵下設定伺服器，並指定 `type: "http"`：

```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 支援引用輸入變數或環境檔案，而不必把 key 寫死。你也可以用命令面板動作 `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 設定的 `mcpServers` 下新增伺服器，Streamable HTTP 使用 `httpUrl`：

```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 時，在 `tools` 陣列中以 `type: "mcp"` 傳入 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 中，於 `mcpServers` 下以 `serverUrl` 欄位設定伺服器：

```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`）。在除錯日誌中，請找與 `blockvectra-docs` 有關的行，例如 `Successfully connected` 與 `Failed to fetch tools`。若伺服器顯示 `connected` 但沒有出現任何工具，請閱讀除錯日誌（`--debug mcp`）在 `Failed to fetch tools` 之後回報的原因。若要確認伺服器本身是否正常，請使用下方的 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` 這類 slug，可從 `list_chains` 取得。需要 key 的工具需要 `x-api-key` 標頭；下面這個呼叫使用環境變數中的 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` 以及該 key 的速率限制。如果你的 agent 透過有權限控管的 shell 執行命令，這種變數展開可能被阻擋；請改在 MCP 用戶端中設定標頭。

## 常見問題

### BlockVectra MCP 伺服器需要 API key 嗎？

不需要。連線不需要 key，15 個工具中有 10 個永遠不需要 key。`rpc_call` 與 `send_raw_transaction` 在沒有 key 時，只能用於該鏈 `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` 只回傳步驟；agent 透過 HTTP 依照[程式化建立帳戶](https://docs.blockvectra.com/zh-hant/guides/programmatic-signup/?ref=docs-mcp-server)建立 key，一般使用者則在控制台建立。key 絕不會經過工具參數。

### Agent 能透過 MCP 伺服器傳送交易嗎？

可以廣播，但不能簽章。`rpc_call` 會拒絕寫入方法，例如 `eth_sendRawTransaction`、`eth_sendTransaction`、`eth_sign` 與 `personal_*`。`send_raw_transaction` 會用 `eth_sendRawTransaction` 廣播你已在本機簽好章的交易；伺服器從不持有或看到私鑰。

### 呼叫失敗時會怎樣？

工具錯誤會回傳 `isError: true` 與結構化的原因。請使用 `explain_error` 或[錯誤碼參考](https://docs.blockvectra.com/zh-hant/errors/)，查看失敗是否計費以及是否應該重試。

## 相關內容

* [連線 AI Agent](https://docs.blockvectra.com/zh-hant/guides/ai-agents/)：機器可讀檔案、公開 JSON 端點與選鏈流程。
* [程式化建立帳戶](https://docs.blockvectra.com/zh-hant/guides/programmatic-signup/?ref=docs-mcp-server)：不用瀏覽器，以錢包簽章建立 API key。
* [Agent 框架配方](https://docs.blockvectra.com/zh-hant/guides/agent-frameworks/)：ElizaOS、viem、wagmi 與 Coinbase AgentKit。
* [錯誤碼](https://docs.blockvectra.com/zh-hant/errors/)：每個錯誤的計費與重試規則。