# Install the SciFig MCP server

Connect an AI assistant to SciFig. Server URL: https://mcp.scifig.ai/mcp. Overview: https://scifig.ai/mcp. Reference: https://scifig.ai/docs/api/mcp.

## Rules for agents doing the installation

- Install only when the user asked for SciFig; do not add it on your own initiative.
- Pick the steps for the client you are running in. If you cannot change its configuration yourself, show the user the exact steps instead.
- Never ask for the user’s password. OAuth clients sign in in the browser; for an API key, ask the user to create it under Settings → API Keys and paste it into the configuration themselves.
- Call `get_credit_balance` only with `credits:read`. If it is missing, explain the limitation and ask before requesting broader access. Do not create a figure to test the connection.
- Report only observed tools and successful checks; do not claim a balance check when `credits:read` was not granted.

## Codex setup and first connection

```bash
codex mcp list
```

First list the configured MCP servers. If `scifig` already exists, inspect it with `codex mcp get scifig`. Reuse it when its URL matches; otherwise explain the difference and ask before changing it. Preserve every unrelated server and setting. Run the add command below only when `scifig` is absent.

```bash
codex mcp add scifig --url https://mcp.scifig.ai/mcp
codex mcp login scifig
```

- Authorize SciFig in the browser opened by `codex mcp login scifig`. The user completes sign-in and approves the requested permissions. If the existing configuration already matches, run only the login command.
- After connecting for the first time, briefly introduce SciFig in the user’s language: it can create and edit scientific illustrations, charts and graphs, and flowcharts, recognize text, upscale images and export figures. Give one example, such as “Draw a labeled mitochondrion diagram.” Do not create it until asked.
- For the initial check, call only `get_credit_balance` when `credits:read` was granted. If that permission is missing, explain it and ask before requesting broader access. Report the actual result; do not generate a figure or spend credits to test the connection.
- Creation and conversion may return a queued or processing job. Keep its job ID. Poll `get_job` until it finishes only when `jobs:read` was granted. If that permission is missing, explain it and ask before requesting broader access. Never repeat the creation call or invent a new idempotency key merely because the assistant stopped waiting.
- Use only the installation methods documented below. Do not invent plugin marketplace commands. Never ask the user to paste a password, API key or OAuth token into chat.

## Install the official SciFig plugin

Add the SciFig marketplace in Claude Code to install the remote MCP connection and four workflow skills for setup, figures, charts and export.

```text
/plugin marketplace add lilingm963/scifig-plugins
/plugin install scifig@scifig-plugins
```

- [API & MCP overview](/developers)
- [MCP installation guide](/developers/mcp/install.md)
- [API reference](/docs/api)
- [Explore the official plugin](https://github.com/lilingm963/scifig-plugins)
- [MCP Registry record](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.lilingm963%2Fscifig/versions/1.0.0)

## MCP server

Server URL: `https://mcp.scifig.ai/mcp` (Streamable HTTP). Clients that support OAuth connect by signing in to SciFig and approving access; clients that send headers can use an API key as `Authorization: Bearer sk_live_…`.

| Tool | What it does |
| --- | --- |
| generate_figure | Create a scientific illustration from a prompt |
| edit_figure | Edit an image: instruction (optionally a masked region), white background, aspect ratio, recolor or text replacement |
| detect_text | Find the text in an image before replacing it |
| upscale_figure | Upscale to 2K, 4K or 8K |
| convert_figure | Convert to SVG, PNG, PDF, TIFF or PPTX |
| generate_chart | Plot a chart from CSV or TSV text or JSON rows (up to 1 MB) |
| edit_chart | Change the latest version of a chart |
| generate_flowchart | Draw a flowchart as SVG, optionally from up to 8 attachments |
| edit_flowchart | Change the latest version of a flowchart |
| get_job | Status, credits and download links of a job |
| list_figures | Recent jobs |
| get_credit_balance | Credit balance, plan and limits |

Creation tools wait up to 25 seconds. If a job is still running, call `get_job` later; calling the creation tool again creates and charges a new job. Results list each download link and, for charts and flowcharts, the link that opens the result in the SciFig editor.

Initialization uses `/capabilities` and does not require `credits:read`. Each tool requires its own scope. External URL/data URL uploads additionally require `files:write`, checked before fetching. Reusing a `file_id` does not. Inline downloads and `get_job` need `jobs:read`; without it, preserve the job result and explain the limitation rather than requesting broader access without consent.

## Connect your client

Claude (claude.ai and Claude Desktop): Settings → Connectors → Add custom connector, enter the server URL, then sign in to SciFig and allow access.

Open ChatGPT `Plugins` and add a custom private MCP connection. Available menus depend on your account.

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"
```

Open Cursor `Customize` → MCP, then edit `mcp.json` without overwriting existing servers. Then select `Authenticate` and approve SciFig in your browser.

```json
{
  "mcpServers": {
    "scifig": {
      "url": "https://mcp.scifig.ai/mcp"
    }
  }
}
```

Clients without OAuth can add the header `Authorization: Bearer sk_live_…` with an API key from Settings → API Keys.