# MCP 伺服器

透過遠端 MCP 伺服器，在 Claude、ChatGPT、Claude Code、Codex 和 Cursor 中使用 SciFig。

來源：https://scifig.ai/zh-Hant/docs/api/mcp

## MCP 伺服器

伺服器 URL：`https://mcp.scifig.ai/mcp`（Streamable HTTP）。支援 OAuth 的用戶端透過登入 SciFig 並批准存取連線；可傳送請求標頭的用戶端可使用 API 金鑰，格式為 `Authorization: Bearer sk_live_…`。

| 工具 | 功能 |
| --- | --- |
| generate_figure | 根據提示詞建立科學插圖 |
| edit_figure | 編輯圖片：指令（可選遮罩區域）、白色背景、寬高比、重新配色或文字替換 |
| detect_text | 替換前識別圖中的文字 |
| upscale_figure | 放大到 2K、4K 或 8K |
| convert_figure | 轉換為 SVG、PNG、PDF、TIFF 或 PPTX |
| generate_chart | 根據 CSV、TSV 文字或 JSON 行資料繪製圖表（最大 1 MB） |
| edit_chart | 修改圖表的最新版本 |
| generate_flowchart | 繪製 SVG 流程圖，也可基於最多 8 個附件 |
| edit_flowchart | 修改流程圖的最新版本 |
| get_job | 任務狀態、點數和下載連結 |
| list_figures | 最近的任務 |
| get_credit_balance | 點數餘額、方案和限制 |

建立工具最多等待 25 秒。任務仍執行時，請稍後呼叫 `get_job`；再次呼叫建立工具會新建並扣費一個任務。結果列出每個下載連結，圖表和流程圖還包含在 SciFig 編輯器中開啟結果的連結。

建立工具會在下載附件前檢查 `figures:generate` 權限範圍。唯讀連線可讀取任務和點數，但無法建立插圖。

## 連線用戶端

Claude（claude.ai 和 Claude Desktop）：設定 → 聯結器 → 新增自訂聯結器，輸入伺服器 URL，再登入 SciFig 並允許存取。

ChatGPT：設定 → 應用程式 → 進階 → 開發者模式，使用伺服器 URL 和 OAuth 驗證建立應用程式。

Claude Code：

```bash
claude mcp add --transport http scifig https://mcp.scifig.ai/mcp
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.scifig]
url = "https://mcp.scifig.ai/mcp"
```

Cursor（`~/.cursor/mcp.json`），使用在設定 → 開發者中建立的 API 金鑰：

```json
{
  "mcpServers": {
    "scifig": {
      "url": "https://mcp.scifig.ai/mcp",
      "headers": { "Authorization": "Bearer sk_live_…" }
    }
  }
}
```

不支援 OAuth 的用戶端，可使用設定 → 開發者中的 API 金鑰新增請求標頭 `Authorization: Bearer sk_live_…`。

## 工具參數

| 工具 | 參數 | 必填 | 規則 |
| --- | --- | --- | --- |
| generate_figure | prompt | 是 | 3–20,000 個字元 |
|  | aspect_ratio | 否 | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|  | quality | 否 | `standard`、`advanced` 或 `premium` |
|  | style | 否 | `flat`, `2-5d`, `line-art`, `hand-drawn`, `scientific`, `line`, `3d`, `editorial`, `sketch`, `watercolor`, `auto` 中的一項 |
|  | palette | 否 | 1–64 個字元的配色名稱，或 1–4 個 `#RRGGBB` 顏色值 |
|  | reference_images | 否 | 最多 3 張圖片：`file_id`、https URL 或 data URL；最大 20 MB 的 PNG、JPEG 或 WebP（data URL 約 3 MB，參閱下文） |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| edit_figure | image | 是 | `file_id`、https URL 或 data URL；最大 20 MB 的 PNG、JPEG 或 WebP（data URL 約 3 MB，參閱下文） |
|  | operation | 否 | `instruct`（預設）、`white_background`、`aspect_ratio`、`recolor` 或 `replace_text` |
|  | instruction | 適用於 `instruct` | 1–2,000 個字元 |
|  | mask | 否 | 僅適用於 `instruct`：最大 8 MB 的 PNG，白色表示允許修改的區域 |
|  | aspect_ratio | 適用於 `aspect_ratio` | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|  | palette | 否 | 僅適用於 `recolor`：1–8 個 `#RRGGBB` 顏色值 |
|  | text_detection | 適用於 `replace_text` | `detect_text` 回傳的 id |
|  | replacements | 適用於 `replace_text` | 1–256 項 `[{"index", "text"}]`：`index` 為 `detect_text` 中的 0–255，每個索引最多出現一次；text 為 1–500 個字元 |
|  | quality | 否 | `replace_text` 會忽略此項 |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| detect_text | image | 是 | `file_id`、https URL 或 data URL；最大 20 MB 的 PNG、JPEG 或 WebP（data URL 約 3 MB，參閱下文） |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| upscale_figure | image | 是 | `file_id`、https URL 或 data URL；最大 20 MB 的 PNG、JPEG 或 WebP（data URL 約 3 MB，參閱下文） |
|  | scale | 是 | `2k`、`4k` 或 `8k` |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| convert_figure | image | 是 | `file_id`、https URL 或 data URL；最大 20 MB 的 PNG、JPEG 或 WebP（data URL 約 3 MB，參閱下文）；或透過 `file_id` 指定流程圖 SVG 輸出 |
|  | format | 是 | `svg`、`png`、`pdf`、`tiff` 或 `pptx` |
|  | vector_mode | 否 | 僅適用於格式 `svg`：`editable_text` 或 `full_vector` |
|  | dpi | 否 | 不適用於 `svg`：300、600 或 1000 |
|  | width | 否 | 不適用於 `svg`；僅用於流程圖 SVG 原始檔：256–4096 畫素 |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| generate_chart | data | `data` 或 `rows` | 帶表頭行的 CSV 或 TSV 文字，最大 1 MB（1,000,000 個字元） |
|  | rows | `data` 或 `rows` | 替代 `data`：1–100,000 個物件，每個物件將列名對映到值；以 CSV 傳送，最大 1 MB |
|  | data_format | 否 | `csv` 或 `tsv`；省略時根據首行識別 |
|  | request | 是 | 需要繪製的內容，1–16,000 個字元 |
|  | chart_types | 否 | 最多 46 種圖表類型，不可重複（參閱[圖表](/zh-Hant/docs/api/charts)） |
|  | journal_style | 否 | `default`、`nature`、`science`、`cell`、`plos` 或 `acs` |
|  | figure_width | 否 | `single`、`onehalf` 或 `double` |
|  | color_palette | 否 | 配色名稱（參閱[圖表](/zh-Hant/docs/api/charts)） |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| edit_chart | job_id | 是 | 最新的圖表任務 |
|  | instruction | 是 | 1–16,000 個字元 |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| generate_flowchart | prompt | 是 | 1–8,000 個字元 |
|  | aspect_ratio | 否 | `auto`, `16:9`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `21:9` |
|  | attachments | 否 | 最多 8 個：`file_id`、https URL 或 data URL；PDF、DOC、DOCX、Markdown、文字、SVG、PNG、JPEG 或 WebP，每個最大 32 MB |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| edit_flowchart | job_id | 是 | 最新的流程圖任務 |
|  | instruction | 是 | 1–8,000 個字元 |
|  | idempotency_key | 否 | 可選；僅在超時或網路錯誤後重試同一請求時複用 |
| get_job | job_id | 是 | 任務 id |
| list_figures | limit | 否 | 1–20 |
|  | cursor | 否 | 上一頁的 `next_cursor` |
| get_credit_balance | — | — | 無參數 |

`generate_chart` 僅接受文字資料，最大 1 MB。Excel 工作簿（及其 `sheet_name`）或更大檔案請使用 [`POST /charts/generations`](/zh-Hant/docs/api/charts)。

## 工具行為

- 伺服器地址為 `https://mcp.scifig.ai/mcp`（Streamable HTTP）。它代表你呼叫本 API，因此價格、點數、限制和錯誤相同。
- 圖片和附件參數接受 `file_id`、https URL 或 data URL；URL 和 data URL 會先透過 `POST /files` 上傳，計入上傳額度。SciFig 自身的 URL 會被拒絕（請傳 `file_id`），重定向僅允許跳轉到其他 https 地址。
- MCP 伺服器單次請求限制為 4 MB。Base64 會使檔案增大約三分之一，因此 data URL 可攜帶約 3 MB；更大檔案請透過 https URL 傳入。
- 伺服器僅在 `initialize` 和 `tools/call` 時檢查憑證。權杖過期或被撤銷時回傳 `401`，便於用戶端更新權杖或重新登入；帳戶被封禁或正在刪除時回傳 `403`。
- 已完成的圖片結果不超過 1 MB 時會內聯顯示；每個結果都包含下載連結，圖表和流程圖結果還包含在 SciFig 編輯器中開啟的連結。
- 除非助手傳入 `idempotency_key`，否則每次建立均使用新的 Idempotency-Key，因此再次請求會新建並扣費一個任務。請用 `get_job` 查詢進度。
- 錯誤結果會回傳 `idempotency_key`，任務存在時還會回傳 `job_id`。超時或伺服器錯誤後，請用相同金鑰重試或呼叫 `get_job`；`402 INSUFFICIENT_CREDITS` 等拒絕響應會保留在原金鑰下，請換新金鑰重發。