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:
- Date un nome al token (l'assistente o il progetto che serve).
- 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.
- Tenete tutte le applicazioni dell'organizzazione, o sceglietene alcune: il token raggiunge allora solo quelle, ovunque.
- Scegliete la sua durata, da 1 a 90 giorni, e lasciate spuntata «Le azioni distruttive attendono qui l'approvazione di un proprietario».
- 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__<applicazione>__<strumento></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).