# Server MCP

Usa SciFig da Claude, ChatGPT, Claude Code, Codex e Cursor tramite il server MCP remoto.

Fonte: https://scifig.ai/it/docs/api/mcp

## Server MCP

URL del server: `https://mcp.scifig.ai/mcp`, Streamable HTTP. I client che supportano OAuth si collegano accedendo a SciFig e autorizzando l’accesso; quelli che inviano intestazioni possono usare una chiave API come `Authorization: Bearer sk_live_…`.

| Strumento | Funzione |
| --- | --- |
| generate_figure | Crea un’illustrazione scientifica da una descrizione |
| edit_figure | Modifica un’immagine: istruzioni, eventualmente una regione mascherata, sfondo bianco, proporzioni, cambio di colori o sostituzione del testo |
| detect_text | Rileva il testo in un’immagine prima di sostituirlo |
| upscale_figure | Ingrandisci a 2K, 4K o 8K |
| convert_figure | Converti in SVG, PNG, PDF, TIFF o PPTX |
| generate_chart | Crea un grafico da testo CSV o TSV o righe JSON, fino a 1 MB |
| edit_chart | Modifica l’ultima versione di un grafico |
| generate_flowchart | Disegna un diagramma di flusso in SVG, eventualmente da un massimo di 8 allegati |
| edit_flowchart | Modifica l’ultima versione di un diagramma di flusso |
| get_job | Stato, crediti e link di download di un processo |
| list_figures | Processi recenti |
| get_credit_balance | Saldo crediti, piano e limiti |

Gli strumenti di creazione attendono fino a 25 secondi. Se un processo è ancora in esecuzione, chiama `get_job` più tardi; richiamare lo strumento di creazione crea e addebita un nuovo processo. I risultati elencano tutti i link di download e, per grafici e diagrammi di flusso, il link che apre il risultato nell’editor SciFig.

Gli strumenti di creazione controllano l’ambito `figures:generate` prima di scaricare gli allegati. Un collegamento di sola lettura può consultare processi e crediti, ma non può creare figure.

## Collega il tuo client

Claude, su claude.ai e in Claude Desktop: Impostazioni → Connettori → Aggiungi connettore personalizzato. Inserisci l’URL del server, accedi a SciFig e consenti l’accesso.

ChatGPT: Impostazioni → Applicazioni → Avanzate → Modalità sviluppatore. Crea un’applicazione con l’URL del server e autenticazione 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, in `~/.cursor/mcp.json`, con una chiave API creata in Impostazioni → Sviluppatore:

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

I client senza OAuth possono aggiungere l’intestazione `Authorization: Bearer sk_live_…` con una chiave API creata in Impostazioni → Sviluppatore.

## Parametri degli strumenti

| Strumento | Parametro | Obbligatorio | Regole |
| --- | --- | --- | --- |
| generate_figure | prompt | sì | 3–20.000 caratteri |
|  | aspect_ratio | no | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|  | quality | no | `standard`, `advanced` o `premium` |
|  | style | no | Uno dei valori `flat`, `2-5d`, `line-art`, `hand-drawn`, `scientific`, `line`, `3d`, `editorial`, `sketch`, `watercolor`, `auto` |
|  | palette | no | Nome di palette di 1–64 caratteri oppure 1–4 colori `#RRGGBB` |
|  | reference_images | no | Fino a 3 immagini: `file_id`, URL https o URL data; PNG, JPEG o WebP fino a 20 MB, circa 3 MB per un URL data, vedi sotto |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| edit_figure | image | sì | `file_id`, URL https o URL data; PNG, JPEG o WebP fino a 20 MB, circa 3 MB per un URL data, vedi sotto |
|  | operation | no | `instruct` come valore predefinito, `white_background`, `aspect_ratio`, `recolor` o `replace_text` |
|  | instruction | per `instruct` | 1–2.000 caratteri |
|  | mask | no | Solo per `instruct`: PNG fino a 8 MB, bianco dove l’immagine può cambiare |
|  | aspect_ratio | per `aspect_ratio` | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|  | palette | no | Solo per `recolor`: 1–8 colori `#RRGGBB` |
|  | text_detection | per `replace_text` | L’identificativo restituito da `detect_text` |
|  | replacements | per `replace_text` | 1–256 elementi `[{"index", "text"}]`: `index` da 0 a 255 da `detect_text`, ogni indice al massimo una volta; text di 1–500 caratteri |
|  | quality | no | Ignorato da `replace_text` |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| detect_text | image | sì | `file_id`, URL https o URL data; PNG, JPEG o WebP fino a 20 MB, circa 3 MB per un URL data, vedi sotto |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| upscale_figure | image | sì | `file_id`, URL https o URL data; PNG, JPEG o WebP fino a 20 MB, circa 3 MB per un URL data, vedi sotto |
|  | scale | sì | `2k`, `4k` o `8k` |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| convert_figure | image | sì | `file_id`, URL https o URL data; PNG, JPEG o WebP fino a 20 MB, circa 3 MB per un URL data, vedi sotto; oppure il risultato SVG di un diagramma di flusso tramite `file_id` |
|  | format | sì | `svg`, `png`, `pdf`, `tiff` o `pptx` |
|  | vector_mode | no | Solo con formato `svg`: `editable_text` o `full_vector` |
|  | dpi | no | Non per `svg`: 300, 600 o 1000 |
|  | width | no | Non per `svg`; solo per sorgenti SVG di diagrammi di flusso: 256–4096 pixel |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| generate_chart | data | `data` oppure `rows` | Testo CSV o TSV con riga di intestazione, fino a 1 MB, pari a 1.000.000 di caratteri |
|  | rows | `data` oppure `rows` | Al posto di `data`: 1–100.000 oggetti che associano nomi di colonne a valori; inviati come CSV, fino a 1 MB |
|  | data_format | no | `csv` o `tsv`; se omesso, viene rilevato dalla prima riga |
|  | request | sì | Cosa rappresentare, 1–16.000 caratteri |
|  | chart_types | no | Fino a 46 tipi di grafici, senza duplicati; vedi [grafici](/it/docs/api/charts) |
|  | journal_style | no | `default`, `nature`, `science`, `cell`, `plos` o `acs` |
|  | figure_width | no | `single`, `onehalf` o `double` |
|  | color_palette | no | Nome di palette; vedi [grafici](/it/docs/api/charts) |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| edit_chart | job_id | sì | Il processo del grafico più recente |
|  | instruction | sì | 1–16.000 caratteri |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| generate_flowchart | prompt | sì | 1–8000 caratteri |
|  | aspect_ratio | no | `auto`, `16:9`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `21:9` |
|  | attachments | no | Fino a 8 file: `file_id`, URL https o URL data; PDF, DOC, DOCX, Markdown, testo, SVG, PNG, JPEG o WebP, fino a 32 MB ciascuno |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| edit_flowchart | job_id | sì | Il processo del diagramma di flusso più recente |
|  | instruction | sì | 1–8000 caratteri |
|  | idempotency_key | no | Facoltativo; riutilizza solo per riprovare la stessa richiesta dopo un timeout o un errore di rete |
| get_job | job_id | sì | Un identificativo di processo |
| list_figures | limit | no | 1–20 |
|  | cursor | no | `next_cursor` della pagina precedente |
| get_credit_balance | — | — | Nessun parametro |

`generate_chart` accetta solo dati di testo, fino a 1 MB. Per le cartelle di lavoro Excel (e il relativo `sheet_name`) o i file più grandi, usa [`POST /charts/generations`](/it/docs/api/charts).

## Funzionamento degli strumenti

- Il server si trova all’indirizzo `https://mcp.scifig.ai/mcp` (Streamable HTTP). Chiama questa API per tuo conto, quindi prezzi, crediti, limiti ed errori sono gli stessi.
- I parametri per immagini e allegati accettano una `file_id`, un URL https o un URL di dati. Gli URL e gli URL di dati vengono prima caricati con `POST /files`, quindi contano nei limiti di caricamento. Gli URL di SciFig vengono rifiutati (passa la `file_id`); i reindirizzamenti sono seguiti solo verso altri indirizzi https.
- Una richiesta al server MCP è limitata a 4 MB. Base64 aumenta le dimensioni di un file di un terzo, quindi un URL di dati può contenere circa 3 MB. Passa i file più grandi come URL https.
- Il server verifica le credenziali solo in `initialize` e `tools/call`. Un token scaduto o revocato restituisce `401`, così il client può aggiornarlo o accedere di nuovo; un account bloccato o in fase di eliminazione restituisce `403`.
- Le immagini completate vengono mostrate direttamente nella conversazione se non superano 1 MB. Ogni risultato include link per il download; grafici e diagrammi di flusso aggiungono un link per aprire il risultato nell’editor SciFig.
- Ogni creazione usa un nuovo Idempotency-Key, a meno che l’assistente non passi `idempotency_key`. Ripetere la richiesta crea e addebita quindi una nuova attività. Usa `get_job` per seguirne l’avanzamento.
- Un risultato di errore restituisce `idempotency_key` e, se esiste un’attività, `job_id`. Dopo un timeout o un errore del server, riprova con la stessa chiave o chiama `get_job`. Un rifiuto come `402 INSUFFICIENT_CREDITS` rimane salvato sotto la sua chiave; in quel caso, invia la richiesta con una nuova chiave.