> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 配置指南

> 5 分鐘完成 ChainStream MCP Server 配置

本指南幫助你快速配置 ChainStream MCP Server。

***

## 前提條件

| 要求             | 詳情                               | 如何獲取                                       |
| -------------- | -------------------------------- | ------------------------------------------ |
| ChainStream 賬號 | 已註冊賬號                            | [註冊](https://www.chainstream.io/dashboard) |
| API Key        | 用於認證的 `X-API-KEY`                | Dashboard → 應用 → 建立應用                      |
| AI 客戶端         | Claude Desktop / Cursor / 自定義客戶端 | 已安裝                                        |

***

## MCP 端點

ChainStream 提供託管的 MCP Server，無需本地安裝 — 直接連線：

```
https://mcp.chainstream.io/mcp
```

***

## 配置步驟

<Steps>
  <Step title="獲取 API Key">
    1. 登入 [ChainStream Dashboard](https://www.chainstream.io/dashboard)
    2. 進入 **Applications**
    3. 點選 **Create New App** 並複製你的 API Key
  </Step>

  <Step title="配置 AI 客戶端">
    <Tabs>
      <Tab title="Claude Desktop">
        **配置檔案路徑**：

        * macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
        * Windows：`%APPDATA%\Claude\claude_desktop_config.json`

        **方式 A — 雲端端點（推薦）**：

        ```json theme={null}
        {
          "mcpServers": {
            "chainstream": {
              "url": "https://mcp.chainstream.io/mcp",
              "headers": {
                "X-API-KEY": "your_api_key"
              }
            }
          }
        }
        ```

        **方式 B — 本地 npm 包（stdio）**：

        ```json theme={null}
        {
          "mcpServers": {
            "chainstream": {
              "command": "npx",
              "args": ["@chainstream-io/mcp"],
              "env": {
                "CHAINSTREAM_API_KEY": "your_api_key"
              }
            }
          }
        }
        ```

        <Note>
          如果檔案不存在，請手動建立。如果已有其他 MCP Server 配置，將 `chainstream` 配置新增到現有的 `mcpServers` 物件中。
        </Note>
      </Tab>

      <Tab title="Cursor IDE">
        **配置檔案路徑**：`.cursor/mcp.json`（專案級）或 Cursor 設定 → Features → MCP Servers

        **方式 A — 雲端端點**：

        ```json theme={null}
        {
          "mcpServers": {
            "chainstream": {
              "url": "https://mcp.chainstream.io/mcp",
              "headers": {
                "X-API-KEY": "your_api_key"
              }
            }
          }
        }
        ```

        **方式 B — 本地 npm 包（stdio）**：

        ```json theme={null}
        {
          "mcpServers": {
            "chainstream": {
              "command": "npx",
              "args": ["@chainstream-io/mcp"],
              "env": {
                "CHAINSTREAM_API_KEY": "your_api_key"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="自定義客戶端">
        透過 HTTP 連線雲端端點：

        | 端點     | URL                              | 方法   |
        | ------ | -------------------------------- | ---- |
        | MCP 端點 | `https://mcp.chainstream.io/mcp` | POST |

        **認證**：透過 `X-API-KEY` 請求頭傳遞 API Key。

        **示例程式碼**：

        ```javascript theme={null}
        import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
        import { Client } from '@modelcontextprotocol/sdk/client/index.js';

        const transport = new StreamableHTTPClientTransport(
          new URL('https://mcp.chainstream.io/mcp'),
          {
            requestInit: {
              headers: {
                'X-API-KEY': process.env.CHAINSTREAM_API_KEY
              }
            }
          }
        );

        const client = new Client({
          name: 'my-client',
          version: '1.0.0'
        });

        await client.connect(transport);

        const { tools } = await client.listTools();
        console.log('Available tools:', tools.map(t => t.name));
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="重啟客戶端">
    配置完成後，完全退出並重啟 AI 客戶端使配置生效。

    * **Claude Desktop**：完全退出（不是最小化），然後重新開啟
    * **Cursor**：重啟 IDE
  </Step>
</Steps>

***

## 驗證配置

### 測試命令

在 AI 客戶端中輸入以下測試問題：

```
Solana 上的 SOL 代币是什么？安全吗？
```

### 預期結果

如果配置成功，AI 應該：

1. 呼叫 `tokens_search` 查詢 SOL 代幣
2. 呼叫 `tokens_analyze` 獲取安全和持有者資料
3. 返回自然語言摘要

<Note>
  如果 AI 沒有呼叫工具或返回錯誤，請參考下方[常見問題](#常見問題)。
</Note>

***

## 常見問題

<AccordionGroup>
  <Accordion title="認證失敗" icon="key">
    **可能原因**：

    1. **API Key 輸入錯誤**
       * 檢查是否有多餘空格
       * 確認完整複製

    2. **API Key 已撤銷或過期**
       * 在 Dashboard 檢查 Key 狀態
       * 如需要可建立新 Key

    3. **請求頭名稱錯誤**
       * 雲端端點：使用 `X-API-KEY` 請求頭
       * npm 包：使用 `CHAINSTREAM_API_KEY` 環境變數

    **解決方案**：

    * 在 Dashboard → Applications 中驗證 Key
    * 直接測試：`curl -H "X-API-KEY: your_key" https://api.chainstream.io/v2/blockchain`
  </Accordion>

  <Accordion title="連線失敗" icon="plug-circle-xmark">
    **可能原因**：

    1. **網路問題**
       * 檢查網路連線
       * 確認可以訪問 `https://mcp.chainstream.io`

    2. **配置格式錯誤**
       * 檢查 JSON 格式是否正確
       * 確認 URL 拼寫正確

    **解決方案**：

    ```bash theme={null}
    curl -I https://mcp.chainstream.io/mcp
    ```
  </Accordion>

  <Accordion title="配置檔案不生效" icon="file-circle-xmark">
    **可能原因**：

    1. **配置檔案路徑錯誤**
       * macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
       * Windows：`%APPDATA%\Claude\claude_desktop_config.json`

    2. **JSON 格式錯誤**
       * 使用 JSON 驗證工具檢查

    3. **客戶端未重啟**
       * 完全退出後重啟

    **解決方案**：

    ```bash theme={null}
    cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool
    ```
  </Accordion>

  <Accordion title="工具呼叫失敗：配額超限" icon="gauge-low">
    **可能原因**：

    1. 套餐配額已耗盡
    2. 請求頻率過高，觸發限流

    **解決方案**：

    * 在 Dashboard 檢視配額使用情況
    * 升級套餐獲取更多配額
  </Accordion>

  <Accordion title="資料返回延遲或超時" icon="clock">
    **可能原因**：

    1. 網路延遲
    2. 查詢資料量過大

    **解決方案**：

    * 檢查網路連線
    * 減少單次查詢資料量
    * 稍後重試
  </Accordion>
</AccordionGroup>

***

## 下一步

<CardGroup cols={2}>
  <Card title="工具目錄" icon="wrench" href="/zh-Hant/docs/ai-agents/mcp-server/tools">
    檢視所有可用工具和使用示例
  </Card>

  <Card title="AI Agent 教程" icon="graduation-cap" href="/zh-Hant/docs/tutorials/ai-agent-with-mcp">
    構建 AI 交易助手
  </Card>
</CardGroup>