Getting Started Dashboard Personas Locations Scenes Predictions Collections Explore Gallery Prompt Style Library User Profiles Settings MCP Server

Server MCP

Il server MCP (Model Context Protocol) di Fellowship Image Maker consente ai client AI — come Claude Desktop, Claude Code o Cursor — di interagire con personas, locations, scene e generare prompt per immagini direttamente senza aprire l'interfaccia web.

Panoramica

MCP è un protocollo standardizzato che permette agli assistenti AI di chiamare strumenti nella tua applicazione. Il server MCP di Fellowship espone 21 strumenti organizzati in quattro categorie:

  • Personas — elencare, visualizzare, creare, aggiornare, eliminare
  • Locations — elencare, visualizzare, creare, aggiornare, eliminare
  • Scenes — elencare, visualizzare, creare, aggiornare, eliminare, collegare/scollegare personas e locations
  • Prompts — generare prompt per immagini da scene, visualizzare cronologia previsioni

Autenticazione

Tutte le richieste MCP richiedono un token API emesso dalla pagina Impostazioni > Chiavi API.

Generare un Token API

  1. Accedi a Fellowship Image Maker.
  2. Vai a Impostazioni → Chiavi API.
  3. Fai clic su Crea Token.
  4. Opzionalmente assegna un nome (es. "Claude Desktop", "Cursor").
  5. Copia il valore del token (mostrato una sola volta; conservalo in sicurezza).
  6. Usa il token nella configurazione del tuo client MCP.

Revocare i Token

I token possono essere revocati in qualsiasi momento dalla pagina Chiavi API. Una volta revocati, non possono essere riutilizzati.

Configurazione dei Client MCP

Claude Desktop

Aggiungi il server a ~/.mcp/mcp.json:

{
  "mcpServers": {
    "fellowship": {
      "type": "http",
      "url": "https://your-domain.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Sostituisci your-domain.com e YOUR_API_TOKEN con l'URL della tua distribuzione e il token generato. Riavvia Claude Desktop per applicare le modifiche.

Claude Code

La stessa configurazione in .mcp.json funziona per Claude Code. Assicurati di abilitare il server anche nelle impostazioni di Claude Code.

Strumenti Disponibili

Personas

Strumento Descrizione
list-personas Elenca le tue personas, 15 per pagina.
get-persona Recupera una persona tramite slug (nome, descrizione, categoria).
create-persona Crea una persona (nome, categoria, descrizione, note).
update-persona Aggiorna i campi della persona tramite slug.
delete-persona Elimina una persona tramite slug.

Categorie: character o object

Locations

Strumento Descrizione
list-locations Elenca le tue locations, 15 per pagina.
get-location Recupera una location tramite slug (nome, descrizione, epoca, atmosfere).
create-location Crea una location (nome, descrizione, epoca, note).
update-location Aggiorna i campi della location tramite slug.
delete-location Elimina una location tramite slug.

Scenes

Strumento Descrizione
list-scenes Elenca le tue scene con conteggi di personas e locations.
get-scene Recupera i dettagli della scena incluse personas e locations collegate.
create-scene Crea una scena (nome, descrizione con sintassi #p:slug / #l:slug).
update-scene Aggiorna i campi della scena tramite slug.
delete-scene Elimina una scena tramite slug.
attach-persona-to-scene Collega una persona a una scena.
detach-persona-from-scene Scollega una persona da una scena.
attach-location-to-scene Collega una location a una scena.
detach-location-from-scene Scollega una location da una scena.

Sintassi Descrizione Scene:

  • Riferisci personas con #p:slug (es. "Un #p:vecchio-cavaliere si erge in #l:torre-castello")
  • Riferisci locations con #l:slug
  • L'AI risolverà questi riferimenti quando genererà i prompt

Prompts

Strumento Descrizione
generate-prompt Genera un prompt per immagini da una scena tramite slug. Restituisce un ID previsione e il testo del prompt generato.
list-predictions Elenca tutte le previsioni (prompt generati) per una scena, dal più recente.

Flusso di Lavoro Esempio

Usando Claude Desktop con il server MCP abilitato:

  1. Crea una persona:

    Usa lo strumento "create-persona":
- Nome: "L'Alchimista"
- Categoria: "character"
- Descrizione: "Una figura misteriosa in vesti tappezzate, occhi brillanti di conoscenza arcana..."

  2. Crea una location:

    Usa lo strumento "create-location":
- Nome: "Laboratorio della Torre"
- Descrizione: "Una torre a spirale piena di apparecchiature alchimiche gorgoglianti..."

  3. Crea una scena:

    Usa lo strumento "create-scene":
- Nome: "Esperimento Alchimico"
- Descrizione: "#p:l-alchimista conduce un rituale pericoloso in #l:laboratorio-della-torre"

  4. Collega la persona e la location:

    Usa "attach-persona-to-scene":
- Scene slug: "esperimento-alchimico"
- Persona slug: "l-alchimista"

Usa "attach-location-to-scene":
- Scene slug: "esperimento-alchimico"
- Location slug: "laboratorio-della-torre"

  5. Genera un prompt:

    Usa lo strumento "generate-prompt":
- Scene slug: "esperimento-alchimico"

    L'AI risolve tutti i riferimenti #p: e #l: e restituisce un prompt dettagliato per immagini.

Autorizzazione

Tutti gli strumenti rispettano le tue politiche di autorizzazione esistenti:

  • Puoi solo elencare/visualizzare/modificare le tue personas, locations e scene
  • Le personas, locations e scene pubbliche sono leggibili da tutti gli utenti
  • Ogni strumento restituisce un errore se mancano permessi

Gestione degli Errori

Se una chiamata strumento fallisce:

  • 401 Unauthorized — Il tuo token è invalido, revocato o scaduto
  • 403 Forbidden — Mancano i permessi per accedere alla risorsa
  • 404 Not Found — La persona/location/scena non esiste
  • 422 Unprocessable Entity — Errore di validazione (es. slug duplicato, campi richiesti mancanti)

Rate Limiting

Le richieste MCP sono limitate a 60 richieste al minuto per utente.

Risoluzione dei Problemi

Gli strumenti non appaiono in Claude Desktop/Code:

  • Verifica che il token sia corretto e non revocato
  • Controlla che l'URL sia raggiungibile e restituisca HTTP 200
  • Assicurati che "type": "http" sia impostato nella configurazione
  • Riavvia l'applicazione client

Errori "Unauthorized":

  • Genera un nuovo token da Impostazioni > Chiavi API
  • Assicurati che l'intera stringa token (senza spazi extra) sia nell'header

Conflitti di slug:

  • Gli slug devono essere univoci all'interno del tuo account
  • Se uno slug è già utilizzato, usa update-{tipo} per modificare l'elemento esistente oppure usa un nome diverso
← Settings