Server MCP

Contit espone un server MCP (Model Context Protocol) che permette ad agenti come Claude Code, Claude Desktop o altri client MCP di leggere i contenuti di un workspace come tool nativi.

L'endpoint è remoto (Streamable HTTP) ed è raggiungibile a:

https://api.contit.cloud/mcp

L'autenticazione avviene tramite un Personal Access Token (PAT) per-utente, inviato come Bearer. Ogni token è legato a un utente e a un workspace, e ne eredita i permessi (lettura / lettura-scrittura, e gli eventuali permessi per tipo di contenuto).

1. Genera un Personal Access Token

Esistono due tipi di PAT, a seconda dell'ambito:

Tipo	Dove si crea	Ambito
Per-workspace	Console → Impostazioni → Sviluppatore → Personal Access Token del workspace	un singolo workspace, con permessi per content type
Admin (multi-workspace)	Profilo utente (IDP) → Personal Access Token	tutti i workspace che amministri; riservato a Owner/Manager della sottoscrizione

Il token (formato ctpat_...) viene mostrato una sola volta: copialo subito.

Con un token admin usi un'unica entry MCP per tutti i tuoi workspace: l'agente sceglie il workspace per ogni operazione (vedi contit_list_workspaces e il parametro workspaceId sotto).

2. Configura l'agente

Claude Code

claude mcp add --transport http contit https://api.contit.cloud/mcp \
  --header "Authorization: Bearer ctpat_xxxxxxxx"

Claude Desktop

Nel file claude_desktop_config.json, tramite mcp-remote con header X-Api-Key (consigliato: evita problemi di parsing dello spazio in Authorization: Bearer):

{
  "mcpServers": {
    "contit": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.contit.cloud/mcp",
        "--header",
        "X-Api-Key: ctpat_xxxxxxxx"
      ]
    }
  }
}

Il PAT (ctpat_…) è accettato indifferentemente come Authorization: Bearer, header X-Api-Key o query ?api_key=.

Tool disponibili

Tool	Descrizione
contit_list_workspaces	Elenca i workspace accessibili (utile per i token admin multi-workspace)
contit_list_content_types	Elenca i content type (schemi) del workspace
contit_query_content	Cerca i contenuti pubblicati di un content type, con paginazione
contit_get_content	Recupera un singolo contenuto pubblicato dato content type e id

Tutti i tool richiedono almeno il permesso di lettura. Con un token per-workspace il workspace è implicito; con un token admin i tool accettano un parametro workspaceId (l'accesso dell'utente a quel workspace è verificato a runtime). I tool di scrittura saranno aggiunti in una versione successiva.

Validazione centralizzata per le app riservate

Le app riservate possono validare lo stesso Personal Access Token in modo centralizzato tramite l'endpoint /connect/introspect, così l'autorità che conosce i token resta unica (l'IDP). Nell'SDK .NET:

var validator = new ContitTokenValidator(appClientId, appClientSecret);
var info = await validator.ValidateAsync(incomingToken);
if (info.Active)
{
    // info.UserId, info.WorkspaceId, info.CanRead, info.CanWrite
}

Per chiamare le API a nome dell'utente con un PAT:

var client = DelegatedContitClient.FromPersonalAccessToken("ctpat_xxxxxxxx");