Collegare un'IA

Il vostro assistente di IA scrive l'applicazione e la conserva su Git; Gluonify la compila e la distribuisce. Con un token di IA di Prism, lo stesso assistente può registrare il repository, avviare una build, seguirla, chiedere il passaggio in produzione, leggere i log e sospendere l'applicazione, tramite MCP, con i ruoli che gli avete dato e nient'altro.

Come funziona

Prism, la console dei clienti, offre un endpoint MCP su https://app.gluonify.io/mcp (JSON-RPC su HTTP, solo strumenti). Ogni strumento esegue lo stesso codice della schermata corrispondente di Prism, con gli stessi controlli: solo la vostra organizzazione, i ruoli del token e le applicazioni che avete scelto. Gauge resta il server MCP degli operatori della piattaforma.

Prima di iniziare

  • Un account proprietario (org:owner) della vostra organizzazione in Prism: solo un proprietario crea, elenca e revoca i token di IA.
  • Un repository che il builder sa compilare, o un'applicazione già distribuita sulla piattaforma.
  • Un client MCP che supporta l'HTTP «Streamable» e un token bearer, come Claude Code.
  • curl e jq per scambiare il segreto del token (o un qualsiasi client HTTP).

1. Creare un token di IA in Prism

In Prism, aprite Accessi, poi la sezione Token di IA:

  1. Date un nome al token (l'assistente o il progetto che serve).
  2. Spunti i suoi ruoli, raggruppati per repository (leggere, modificare, impostare i token Git), pipeline (leggere, avviare, approvare le promozioni), applicazioni (leggere, sospendere e risvegliare, eliminare, tornare a una versione, ridimensionare), configurazione (leggere, modificare), segreti (sola scrittura), consumi e contratto (leggere, senza prezzi) e metriche (leggere). Spunti solo ciò che serve all'assistente.
  3. Tenete tutte le applicazioni dell'organizzazione, o sceglietene alcune: il token raggiunge allora solo quelle, ovunque.
  4. Scegliete la sua durata, da 1 a 90 giorni, e lasciate spuntata «Le azioni distruttive attendono qui l'approvazione di un proprietario».
  5. Createlo, copiate subito il suo segreto (gai_…) e conservatelo nell'archivio dei segreti del vostro client: Prism lo mostra una sola volta.

2. Scambiare il segreto con un token di accesso

Il segreto non viene inviato all'endpoint MCP stesso: il client lo scambia con un token di accesso breve (circa dieci minuti), poi usa quel token. Prism inoltra lo scambio a Charm, così al client basta l'indirizzo di Prism:

Scambio (il segreto in GLUONIFY_AI_TOKEN, il token di accesso in GLUONIFY_ACCESS_TOKEN)

export GLUONIFY_ACCESS_TOKEN=$(curl -s -X POST https://app.gluonify.io/api/v1/ai/exchange \
  -H 'Content-Type: application/json' \
  -d "{\"refreshToken\":\"$GLUONIFY_AI_TOKEN\"}" | jq -r .access_token)

Quando il token di accesso scade (401), scambiate di nuovo il segreto. Un token di IA revocato o scaduto non si scambia più. Prism non registra mai il segreto.

3. Collegare il vostro client MCP

Dichiarate Prism come server MCP HTTP, con il token di accesso nell'intestazione Authorization:

Configurazione del client MCP (per esempio .mcp.json per Claude Code)

{ "mcpServers": { "gluonify": { "type": "http", "url": "https://app.gluonify.io/mcp", "headers": { "Authorization": "Bearer ${GLUONIFY_ACCESS_TOKEN}" } } } }

Per verificare il collegamento, elencate gli strumenti a mano: sono elencati solo quelli permessi dai ruoli del token.

Elencare gli strumenti

curl -s https://app.gluonify.io/mcp -H "Authorization: Bearer $GLUONIFY_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Che cosa può fare l'assistente

  • Repository: repos_list, repo_get, repo_set (URL, branch, sottocartella), repo_git_token_set (sola scrittura, mai riletto), workflows_standard_copy (copia i workflow standard Build e Promotion nel vostro repository, su un nuovo branch da unire).
  • Pipeline: pipelines_list, pipeline_set (Build o Promotion, riferimento Git, quattro occhi), build_start, build_cancel, builds_list, build_logs, executions_list, execution_get, approval_decide (da QUA a PRD).
  • Applicazioni: apps_list, app_status, app_logs, app_sleep (congelata o arrestata), app_wake, app_sleep_settings, app_delete.

Gli strumenti MCP propri della sua applicazione

Un'applicazione del cliente può esporre i propri strumenti MCP. La piattaforma li inoltra al suo assistente IA tramite l'endpoint MCP di Prism, con il nome <code>app__&lt;applicazione&gt;__&lt;strumento&gt;</code>.

Java (Quarkus)

Aggiunga la dipendenza <code>io.gluonify.plasma:gluonify-plasma-mcp</code>, poi annoti un metodo pubblico di un bean che implementa <code>McpToolbox</code> con <code>@McpTool(name, description, write = false)</code>. Gli argomenti sono un record.

// pom.xml: io.gluonify.plasma:gluonify-plasma-mcp
@ApplicationScoped
public class OrdersToolbox implements McpToolbox {
    public record OrderQuery(String customer, int limit) {}

    @McpTool(name = "orders_list", description = "List the latest orders of a customer", write = false)
    public List<Order> ordersList(OrderQuery query) {
        return orders.latest(query.customer(), query.limit());
    }
}

Python

Importi <code>mcp_tool</code> da <code>gluonify.fastapi</code>, decori una funzione e chiami <code>create_app(..., mcp=True)</code>.

from gluonify.fastapi import create_app, mcp_tool

@mcp_tool(name="orders_list", description="List the latest orders of a customer", write=False)
def orders_list(customer: str, limit: int = 10) -> list[dict]:
    return latest_orders(customer, limit)

app = create_app(__name__, mcp=True)
  • Il builder rileva l'SDK e distribuisce l'applicazione con MCP attivo.
  • Gli strumenti di lettura richiedono il permesso IA di leggere le applicazioni. Quelli di scrittura sono proposti a un proprietario per approvazione (in produzione).
  • L'applicazione accetta solo le chiamate inoltrate dalla piattaforma.
  • Limiti: 50 strumenti, argomenti di 64 KiB, risposta di 256 KiB, 10 s per chiamata.
  • Gli strumenti compaiono nella console (vista dell'applicazione, «Strumenti MCP») e un proprietario può aggiornarli.

Le protezioni

Un token di IA non è una persona: Prism lo limita di più.

  • Mai un potere da proprietario: un token di IA non gestisce gli accessi, i token di IA, l'audit né i domini, non vede mai un prezzo, e funziona solo sul punto di accesso MCP.
  • Solo la vostra organizzazione, e solo le applicazioni scelte: tutto il resto risponde come se non esistesse.
  • Nessuna auto-approvazione: un token non approva mai la promozione di un'esecuzione che ha avviato.
  • Un limite di chiamate per token (60 al minuto e 1000 all'ora per impostazione predefinita); oltre, il client deve attendere.
  • Modalità approvazione: eliminare un'applicazione, approvare una promozione, impostare un token Git, scrivere o eliminare un segreto, tornare a una versione o ridimensionare un'applicazione diventa una proposta che un proprietario approva o rifiuta in Accessi; approvata, viene eseguita con i ruoli del token stesso.

Audit

Ogni chiamata di un token di IA è registrata nel modulo Audit di Prism: quale token (il suo nome), quale strumento, quale applicazione e l'esito, mai un segreto. Spuntate «Solo token di IA» per vedere solo quelle. L'elenco dei token mostra il loro ultimo uso.

Buone pratiche

  • Un token per assistente e per progetto, con il minor numero di ruoli possibile e una durata breve.
  • Iniziate con i ruoli di lettura, poi aggiungete le modifiche che volete davvero.
  • Mantenete la modalità approvazione per le azioni distruttive e approvate voi le promozioni.
  • Revocate un token appena non serve più, o se il suo segreto può essere trapelato.

Partire da gluonify-source

gluonify-source è l'applicazione di partenza per i clienti: un servizio Quarkus in cui ogni scelta è spiegata, con un CLAUDE.md che riassume le regole della piattaforma per un assistente di IA. Avviate il vostro assistente da lì, poi collegatelo a Prism per compilare e distribuire ciò che scrive.

E Gauge?

Gauge è il server MCP degli operatori della piattaforma, con i loro ruoli e le loro politiche. Come clienti, collegate il vostro assistente a Prism, che tiene tutto nella vostra organizzazione.

Limiti

La modalità approvazione, le proposte e i contatori di chiamate sono tenuti in memoria da ogni replica di Prism: dopo un riavvio un token torna in modalità approvazione. Consumi, contratto e quote riguardano tutta l'organizzazione: un token limitato ad alcune applicazioni non può leggerli. Il punto di accesso MCP risponde solo in JSON (nessun flusso di eventi).