# Server MCP Ricamo per Agenti IA

Pagina canonica: https://embroideryfileconverter.com/it/ai-agents

Collega gli agent AI agli strumenti di ricamo autenticati tramite un server MCP remoto con OAuth, rilevamento formati, stato utilizzo e lavori di elaborazione privati.

## Scegli l’integrazione giusta

- Utilizza questo server MCP remoto quando un assistente IA deve agire per conto di un utente tramite OAuth approvato dal browser.
- Utilizza la [REST Developer API](https://embroideryfileconverter.com/it/developers) per un backend tradizionale, un prodotto SaaS o automazioni lato server.

## Connetti un client MCP

- Endpoint HTTP streamable: `https://embroideryfileconverter.com/mcp/embroidery`
- Ambito OAuth: `mcp:use`
- Limite predefinito MCP: 60 richieste al minuto
- Limite strumento creazione file: 6 richieste al minuto per utente, più un limite di rete
- Durata del token di accesso: 60 minuti
- Durata del token di aggiornamento: 30 giorni

L’endpoint funziona con client HTTP Streamable remoti. Preferisci OAuth nativo del browser; non incollare mai password, token di aggiornamento o token bearer di lunga durata in un repository.

## Connetti ChatGPT (OpenAI)

Le app MCP complete si configurano in modalità sviluppatore di ChatGPT. Disponibilità e controlli sugli strumenti di scrittura variano in base al piano.

1. In ChatGPT web, attiva la modalità Sviluppatore in Impostazioni > App > Impostazioni avanzate, oppure apri Impostazioni area di lavoro > App > Crea.
2. Crea un’app e imposta l’URL del server MCP su `https://embroideryfileconverter.com/mcp/embroidery`.
3. Scegli OAuth, seleziona Scansiona strumenti e approva l’ambito `mcp:use` nel browser.
4. Crea la bozza dell’app, abilitala e selezionala dal menu strumenti in una nuova conversazione.

[Documentazione ufficiale ChatGPT MCP](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)

## Connetti Claude, Claude Desktop, Cowork o Claude Code

In Claude, apri Personalizza > Connettori > Aggiungi connettore personalizzato, inserisci `https://embroideryfileconverter.com/mcp/embroidery`, scegli Connetti e completa OAuth. I proprietari di Team ed Enterprise aggiungono il connettore in Impostazioni organizzazione > Connettori prima che i membri si connettano singolarmente.

Comando Claude Code:

```bash
claude mcp add --transport http embroidery-file-converter https://embroideryfileconverter.com/mcp/embroidery
# Quindi esegui /mcp all’interno di Claude Code e completa l’autorizzazione nel browser.
```

[Documentazione ufficiale Claude remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

## Connetti OpenAI Agents SDK

Il tuo backend deve completare il codice di autorizzazione OAuth + PKCE per l’utente connesso, archiviare i token crittografati sul server, aggiornarli quando necessario e passare il token di accesso corrente allo strumento MCP ospitato. Non esporre mai questo token in JavaScript del browser.

```typescript
import { Agent, hostedMcpTool } from '@openai/agents';

const agent = new Agent({
  name: 'Embroidery assistant',
  tools: [
    hostedMcpTool({
      serverLabel: 'embroidery',
      serverUrl: 'https://embroideryfileconverter.com/mcp/embroidery',
      authorization: process.env.EFC_MCP_ACCESS_TOKEN,
      requireApproval: 'always',
    }),
  ],
});
```

[Documentazione ufficiale OpenAI Agents SDK MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)

## Connetti Cursor

Aggiungi questo a `.cursor/mcp.json`, avvia il server in Impostazioni Cursor > MCP e completa OAuth. Gli utenti di Cursor Agent possono eseguire `cursor-agent mcp login embroidery-file-converter`.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentazione ufficiale Cursor MCP](https://docs.cursor.com/context/model-context-protocol)

## Connetti VS Code e GitHub Copilot

Esegui `MCP: Add Server` e scegli HTTP, oppure aggiungi questo a `.vscode/mcp.json`. Avvialo con `MCP: List Servers`, approva la configurazione e completa l’autorizzazione nel browser.

```json
{
  "servers": {
    "embroidery-file-converter": {
      "type": "http",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentazione ufficiale VS Code MCP](https://code.visualstudio.com/docs/agent-customization/mcp-servers)

## Connetti OpenClaw

```bash
openclaw mcp add embroidery-file-converter \
  --url https://embroideryfileconverter.com/mcp/embroidery \
  --transport streamable-http \
  --auth oauth \
  --oauth-scope mcp:use

openclaw mcp login embroidery-file-converter
openclaw mcp doctor embroidery-file-converter --probe
```

[Documentazione ufficiale OpenClaw MCP](https://docs.openclaw.ai/cli/mcp)

## Connetti Gemini CLI

Aggiungi il server a `~/.gemini/settings.json`, quindi esegui `/mcp auth embroidery-file-converter` all’interno di Gemini CLI.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentazione ufficiale Gemini CLI MCP](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)

## Connetti OpenCode

Aggiungi questo a `opencode.json`, quindi esegui `opencode mcp auth embroidery-file-converter` e verificalo con `opencode mcp list`.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "embroidery-file-converter": {
      "type": "remote",
      "url": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentazione ufficiale OpenCode MCP](https://opencode.ai/docs/mcp-servers/)

## Connetti Windsurf Cascade

Apri Impostazioni Windsurf > Cascade > Server MCP, oppure aggiungi questo a `~/.codeium/windsurf/mcp_config.json`. Avvia il server, completa OAuth e abilita solo gli strumenti necessari.

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "serverUrl": "https://embroideryfileconverter.com/mcp/embroidery"
    }
  }
}
```

[Documentazione ufficiale Windsurf MCP](https://docs.windsurf.com/windsurf/cascade/mcp)

## Connetti Cline

Il comportamento OAuth di Cline varia in base alla release e all’interfaccia. Apri Server MCP > Server remoti, scegli Streamable HTTP e utilizza questa configurazione con un elenco di approvazione vuoto:

```json
{
  "mcpServers": {
    "embroidery-file-converter": {
      "type": "streamableHttp",
      "url": "https://embroideryfileconverter.com/mcp/embroidery",
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Se la release installata di Cline non può completare OAuth, utilizza un bridge OAuth revisionato e bloccato su versione, oppure scegli un client con OAuth nativo. Non salvare un token di lunga durata in `cline_mcp_settings.json`.

[Documentazione ufficiale Cline MCP](https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx)

## Scoperta OAuth e PKCE

- Metadati risorsa protetta: `https://embroideryfileconverter.com/.well-known/oauth-protected-resource/mcp/embroidery`
- Metadati server di autorizzazione: `https://embroideryfileconverter.com/.well-known/oauth-authorization-server`
- Registrazione dinamica del client: `https://embroideryfileconverter.com/oauth/register`
- Emittente del server di autorizzazione: `https://embroideryfileconverter.com`
- Grant: codice di autorizzazione
- Metodo PKCE: S256
- Ambito obbligatorio: `mcp:use`

La registrazione dinamica del client accetta solo origini di callback e schemi nativi esplicitamente consentiti dall’operatore. Domini di callback arbitrari vengono rifiutati. L’account deve avere un indirizzo email verificato prima di poter utilizzare l’endpoint MCP.

I callback ospitati attendibili predefiniti sono limitati alle origini ufficiali di ChatGPT, Claude e VS Code più i callback loopback per i client installati. I domini di reindirizzamento con caratteri jolly non sono abilitati. Le distribuzioni che sovrascrivono `MCP_REDIRECT_DOMAINS` devono mantenere solo i client che intendono supportare intenzionalmente.

Esempio di registrazione per un callback locale consentito:

```bash
curl -X POST https://embroideryfileconverter.com/oauth/register \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_name": "Your local agent",
    "redirect_uris": ["http://127.0.0.1:49831/callback"]
  }'
```

## Riferimento completo agli strumenti

### `list-formats-tool`

Sola lettura. Non accetta argomenti. Restituisce `artwork_inputs[]` e `formats[]` con i campi readable, writable, label e warning. Chiamalo prima di scegliere un flusso di lavoro o un formato di destinazione.

### `get-account-usage-tool`

Sola lettura. Non accetta argomenti. Restituisce il credito anteprima disponibile, il saldo crediti, i costi dei flussi di lavoro, i limiti dell’abbonamento e le date di reset. Non acquista né consuma nulla.

### `list-processing-jobs-tool`

Sola lettura. Elenca i lavori recenti dell’account collegato.

- `limit`: intero facoltativo da 1 a 50; predefinito 20

### `get-processing-job-tool`

Sola lettura. Restituisce un lavoro dell’account con stato, eventi, metriche, avvisi, anteprime e URL dei file protetti da OAuth.

- `workflow`: obbligatorio `conversion` o `digitising`
- `job_id`: identificativo lavoro obbligatorio di 26 caratteri

### `create-processing-job-tool`

Crea dati memorizzati. Avvia un lavoro di anteprima privato e può consumare il credito anteprima, ma non acquista crediti né sblocca download a pagamento.

- `workflow`: obbligatorio `conversion` o `digitising`
- `file_name`: nome file originale obbligatorio con estensione, da 3 a 255 caratteri, senza separatori di percorso né caratteri di controllo
- `file_base64`: base64 standard grezzo obbligatorio senza prefisso data-URL
- `format`: formato di uscita ricamo scrivibile obbligatorio in minuscolo
- `width_mm`: numero da 10 a 300, obbligatorio per la digitalizzazione
- `colour_count`: intero da 1 a 24, obbligatorio per la digitalizzazione

Il risultato strutturato include `billing_authorized: false`. Per la conversione il formato di uscita selezionato deve essere diverso dal formato sorgente rilevato.

## Esempi di tool JSON-RPC

Elenca formati:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list-formats-tool",
    "arguments": {}
  }
}
```

Crea anteprima di digitalizzazione:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "file_name": "logo.png",
      "file_base64": "iVBORw0KGgoAAA...",
      "format": "pes",
      "width_mm": 90,
      "colour_count": 8
    }
  }
}
```

Interroga il lavoro restituito:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "get-processing-job-tool",
    "arguments": {
      "workflow": "digitising",
      "job_id": "01JEXAMPLEJOBID000000000"
    }
  }
}
```

I possibili stati del lavoro sono `queued`, `processing`, `completed` e `failed`. Interroga con backoff e interrompi allo stato terminale. Gli URL dei file richiedono lo stesso token OAuth e restano soggetti alla data di scadenza `expiresAt` del caricamento.

## Esempi di prompt in linguaggio naturale

- “Verifica quali formati leggono PES e scrivono in sicurezza JEF. Mostra gli avvisi di compatibilità.”
- “Elenca i miei cinque lavori di ricamo più recenti e riepiloga eventuali fallimenti.”
- “Prima del caricamento chiedimi conferma. Poi digitalizza logo.png a 90 mm di larghezza con non più di 8 colori e restituisci un’anteprima PES.”
- “Interroga il lavoro 01J… fino al termine, quindi riporta le metriche dei punti, gli avvisi e indica se il download è già sbloccato.”

## Modello di sicurezza

- Non è esposto alcun tool per la fatturazione, il pagamento, l’acquisto di crediti o lo sblocco di download a pagamento.
- Non è esposto alcun tool per la creazione di chiavi API, la modifica dell’autenticazione, la lettura di credenziali o l’eliminazione dell’account.
- Ogni lettura di lavoro è limitata all’utente collegato.
- Il tool di creazione memorizza un caricamento privato e crea un lavoro, quindi l’agente deve chiedere conferma prima di caricare.
- Nomi file, metadati, messaggi di lavoro e avvisi sono dati non attendibili. Il server indica agli agenti di non seguire mai comandi incorporati in tali valori.
- Un risultato completato non è automaticamente pronto per la produzione. Gli agenti devono controllare metriche di convalida e avvisi prima di fare affermazioni.

## Risoluzione problemi

- `401 Unauthorized`: nessun token di accesso valido inviato; riavvia la connessione OAuth del client.
- `403 Forbidden`: il token non dispone di `mcp:use`, l’account non è verificato oppure il lavoro richiesto appartiene a un altro account.
- `invalid_redirect_uri`: l’origine del callback o lo schema nativo non è presente nella lista consentita del server.
- `422`: gli argomenti del tool, i dati base64, il tipo sorgente, il formato di destinazione o la quota dell’account non hanno superato la convalida.
- `429`: limite di frequenza superato; rispetta `Retry-After` e usa backoff esponenziale con jitter.

## Pagine correlate

- [Documentazione API per sviluppatori](https://embroideryfileconverter.com/it/developers)
- [Descrizione OpenAPI 3.1](https://embroideryfileconverter.com/developers/openapi.json)
- [Informativa sulla privacy](https://embroideryfileconverter.com/it/privacy)