Installazione

Colleghi qualsiasi client MCP — Claude, Cursor, VS Code, OpenAI Codex, Gemini, Mistral — al server MCP di Certivant usando la Sua chiave API Certivant esistente come token bearer.

Il server MCP di Certivant usa il protocollo Streamable HTTP su un unico endpoint, POST /mcp, e si autentica con una chiave API Certivant inviata come token bearer. Non c'è alcuna credenziale MCP separata da predisporre.

Prima di iniziare

Ottenga una chiave API. La crei nella dashboard in KYC → Sviluppatore (solo Proprietario o Amministratore). Inizia con kyk_ e viene mostrata una sola volta — vedi Autenticazione.

Assegni gli ambiti giusti. kyc:read basta per lo smistamento, le spiegazioni e i report. Aggiunga kyc:write per inviare moduli, avviare verifiche, sollecitare, rinnovare e inviare i dati KYB. kyc:submit serve per inoltrare una richiesta all'elaborazione. Il server MCP inoltra la Sua chiave così com'è — uno strumento per il quale non ha l'ambito restituisce il 403 della stessa API REST.

Conosca l'URL del Suo server. Se è Certivant a gestire il server MCP per Lei, usi l'host che Le è stato fornito. Se lo gestisce Lei, ascolta su MCP_PORT (predefinito 3007) e comunica con l'applicazione a CERTIVANT_API_BASE_URL (predefinito http://localhost:3005).

Tratti la chiave API di questi file di configurazione esattamente come una password. Chiunque la possieda può agire sulla Sua organizzazione con i suoi ambiti — incluso l'invio di email reali ai Suoi clienti.

Avvii il server

Se ospita il server in proprio insieme al resto della piattaforma:

# from the repo root
MCP_PORT=3007 \
CERTIVANT_API_BASE_URL=https://app.certivant.com \
pnpm --filter @repo/mcp start

Verifichi che sia attivo — questo endpoint è volutamente senza autenticazione e segnala solo che il processo è in ascolto, mai che la REST API sia integra:

curl http://localhost:3007/health
# → {"status":"ok","service":"certivant","transport":"streamable-http",…}

Funziona con qualsiasi client MCP

Il server MCP di Certivant segue l'open Model Context Protocol, quindi non è legato a Claude né a un singolo fornitore. Qualsiasi assistente, editor, CLI o piattaforma che parli MCP su Streamable HTTP può usarlo — Claude Desktop e Claude Code, Cursor, VS Code, OpenAI Codex, Google Gemini, Mistral e i nuovi client che arrivano continuamente.

Qualunque client usi, la forma è la stessa: indirizzi il client a POST https://your-mcp-host/mcp e invii la Sua chiave API Certivant come Authorization: Bearer kyk_…. Il resto è il formato di configurazione di quel client. Di seguito quelli più comuni — se il Suo non è elencato, usi lo stesso URL e lo stesso header nelle sue impostazioni MCP e funzionerà.

Configuri un host nativo MCP

Questi host leggono un file di configurazione (oppure un'interfaccia di impostazioni) e si collegano al server per Lei. Incolli l'endpoint e la Sua chiave, e gli strumenti compaiono nell'assistente.

Lo aggiunga dalla CLI:

claude mcp add --transport http certivant https://your-mcp-host/mcp \
  --header "Authorization: Bearer kyk_live_…"

Poi verifichi che sia connesso:

claude mcp list

Modifichi ~/.cursor/mcp.json (globale) oppure .cursor/mcp.json nel progetto:

{
  "mcpServers": {
    "certivant": {
      "url": "https://your-mcp-host/mcp",
      "headers": {
        "Authorization": "Bearer kyk_live_…"
      }
    }
  }
}

Crei .mcp.json nello spazio di lavoro (oppure lo aggiunga al Suo mcp.json utente). Chieda la chiave al momento invece di committarla:

{
  "inputs": [
    {
      "id": "certivant-key",
      "type": "promptString",
      "description": "Certivant API key (kyk_…)",
      "password": true
    }
  ],
  "servers": {
    "certivant": {
      "type": "http",
      "url": "https://your-mcp-host/mcp",
      "headers": {
        "Authorization": "Bearer ${input:certivant-key}"
      }
    }
  }
}

Il file claude_desktop_config.json di Claude Desktop avvia server locali, quindi un endpoint HTTP remoto viene collegato con mcp-remote:

{
  "mcpServers": {
    "certivant": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-mcp-host/mcp",
        "--header",
        "Authorization: Bearer kyk_live_…"
      ]
    }
  }
}

Riavvii Claude Desktop dopo aver modificato il file.

Codex legge ~/.codex/config.toml (oppure un .codex/config.toml di progetto in una cartella attendibile). Aggiunga un server Streamable HTTP e prenda la chiave da una variabile d'ambiente, così non viene salvata in chiaro:

[mcp_servers.certivant]
url = "https://your-mcp-host/mcp"
bearer_token_env_var = "CERTIVANT_API_KEY"

Oppure lo aggiunga dalla CLI:

export CERTIVANT_API_KEY=kyk_live_…
codex mcp add certivant \
  --url https://your-mcp-host/mcp \
  --bearer-token-env-var CERTIVANT_API_KEY

Codex invia il valore come Authorization: Bearer <token>. Per un header diverso da Authorization, usi http_headers al posto di bearer_token_env_var.

Aggiunga il server a ~/.gemini/settings.json (oppure a un .gemini/settings.json di progetto). La chiave httpUrl seleziona il trasporto Streamable HTTP:

{
  "mcpServers": {
    "certivant": {
      "httpUrl": "https://your-mcp-host/mcp",
      "headers": {
        "Authorization": "Bearer kyk_live_…"
      }
    }
  }
}

Costruisca un agente proprio (API e framework)

La sezione precedente riguarda i client già pronti che si puntano sul server — Claude, Cursor, VS Code, OpenAI Codex, Gemini CLI. Questa sezione è per costruire un proprio agente nel codice. Ogni API di fornitori di modelli che supporta MCP remoto funziona — l'API Responses di OpenAI, l'API Messages di Anthropic, Google Gemini, Mistral — così come i framework di agenti indipendenti dal modello, il Vercel AI SDK e LangChain, che espongono gli strumenti Certivant al modello che sceglie. Tutti parlano lo stesso trasporto Streamable HTTP, quindi gli stessi strumenti sono disponibili ovunque.

Chi stabilisce la connessione conta.

Connettori ospitati dal fornitore — l'API Responses di OpenAI, l'API Messages di Anthropic, Gemini e il connettore di Mistral chiamano il Suo server MCP dal loro cloud. Quindi l'endpoint deve essere raggiungibile da Internet (un server di sviluppo su http://localhost:3007 non funzionerà — usi l'host HTTPS distribuito), e la Sua chiave API viaggia verso quel fornitore.
Client di framework — il Vercel AI SDK e LangChain si collegano dal Suo codice, quindi la chiave resta nel Suo processo e un endpoint locale va bene.

In entrambi i casi, limiti la chiave al minimo necessario per il flusso di lavoro, e preferisca una chiave solo kyc:read per le esecuzioni autonome o senza supervisione — una chiave kyc:write permette a un modello di inviare email reali ai Suoi clienti senza un essere umano nel ciclo, a meno che non la vincoli.

L'API Responses accetta un server MCP remoto direttamente in tools. Recupera l'elenco degli strumenti dal server e lascia che il modello lo richiami.

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "certivant",
            "server_url": "https://your-mcp-host/mcp",
            "headers": {"Authorization": "Bearer kyk_live_…"},
            # Gate write tools rather than skipping every prompt — see below.
            "require_approval": "always",
        }
    ],
    input="What's in my verification queue today?",
)

print(resp.output_text)

require_approval: "never" salta la conferma umana per ogni strumento, inclusi quelli che inviano email ai clienti, avviano verifiche o inviano solleciti. Per un uso senza supervisione, o mantenga "always", oppure passi un oggetto che approva automaticamente solo gli strumenti di lettura, oppure usi una chiave solo kyc:read, così non esiste alcuno strumento di scrittura da richiamare.

La stessa voce tools funziona dall'SDK Node e da una chiamata diretta POST https://api.openai.com/v1/responses.

L'API Messages di Claude collega direttamente un server MCP remoto — un utile promemoria che Certivant è un server standard, non specifico per Claude.

import anthropic

client = anthropic.Anthropic()

resp = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What's in my verification queue today?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://your-mcp-host/mcp",
            "name": "certivant",
            "authorization_token": "kyk_live_…",  # sent as Authorization: Bearer
        }
    ],
    betas=["mcp-client-2025-04-04"],
)

Il connettore MCP di Anthropic è in beta e in continua evoluzione — sia la versione dell'header beta sia il fatto che il server venga passato in mcp_servers oppure dentro l'array tools sono cambiati. Consideri lo snippet a titolo illustrativo e segua la documentazione attuale del connettore MCP per la forma esatta.

L'SDK di Google si collega tramite una sessione client MCP. Apra una sessione Streamable HTTP verso il server e la passi a generate_content come strumento.

import asyncio
from google import genai
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

client = genai.Client()

async def main():
    async with streamablehttp_client(
        "https://your-mcp-host/mcp",
        headers={"Authorization": "Bearer kyk_live_…"},
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            resp = await client.aio.models.generate_content(
                model="gemini-2.0-flash",
                contents="What's in my verification queue today?",
                config=genai.types.GenerateContentConfig(tools=[session]),
            )
            print(resp.text)

asyncio.run(main())

Il supporto MCP di Gemini è sperimentale e, al momento della stesura, chiama solo gli strumenti — le risorse e i prompt del server vengono ignorati. Gli strumenti sono la parte essenziale, quindi raramente è un problema in pratica.

Mistral si collega tramite un connettore che si aggiunge in Le Chat oppure in La Plateforme, anziché nel codice. Mistral richiede lo stesso trasporto Streamable HTTP e la stessa autenticazione bearer che il server già usa.

Apra Connettori in Le Chat (oppure nelle impostazioni di Studio / Agents).

Aggiunga un connettore MCP e incolli l'URL del Suo server, https://your-mcp-host/mcp.

Scelga Token bearer HTTP come metodo di autenticazione e incolli la Sua chiave kyk_…. Mistral supporta anche OAuth 2.1 per i server che lo offrono — vedi la nota in fondo a questa pagina.

Salvi. Mistral esegue l'handshake initialize di MCP ed elenca gli strumenti.

Il connettore di Mistral richiede HTTPS con un certificato TLS valido e un server che risponda 200 e risponda alla chiamata initialize. L'host Certivant distribuito lo soddisfa; un server di sviluppo in HTTP semplice o con certificato autofirmato no.

L'AI SDK si collega al server ed espone i suoi strumenti a qualsiasi modello che pilota con generateText / streamText — un'unica integrazione, tutti i modelli.

import { experimental_createMCPClient as createMCPClient } from "ai";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const mcp = await createMCPClient({
  transport: new StreamableHTTPClientTransport(
    new URL("https://your-mcp-host/mcp"),
    { requestInit: { headers: { Authorization: "Bearer kyk_live_…" } } },
  ),
});

const tools = await mcp.tools();
// hand `tools` to generateText({ model, tools, prompt }) with any provider's model

createMCPClient è ancora contrassegnato come experimental_ nell'AI SDK.

langchain-mcp-adapters trasforma gli strumenti del server in strumenti LangChain per qualsiasi agente LangChain o LangGraph, su qualsiasi modello.

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "certivant": {
            "transport": "streamable_http",
            "url": "https://your-mcp-host/mcp",
            "headers": {"Authorization": "Bearer kyk_live_…"},
        }
    }
)

tools = await client.get_tools()
# give `tools` to any LangGraph / LangChain agent

Verifichi la connessione

Chieda all'assistente «cosa c'è nella mia coda di verifica oggi?». Dovrebbe chiamare get_todays_queue e rispondere con dei conteggi. Se invece vede un errore di autenticazione, il server Le indica quale dei tre casi di errore ha incontrato:

Risposta	Causa
`Missing Authorization header…`	L'host non invia affatto l'header — controlli ortografia e virgolette nella configurazione.
`Malformed Authorization header…`	Il valore non ha la forma `Bearer <token>`.
`Bearer token does not look like a Certivant API key…`	Al token manca il prefisso `kyk_`.
Un 401/403 da una chiamata di strumento	La chiave è non valida, revocata oppure non ha l'ambito richiesto. Il server MCP non convalida le chiavi — quel verdetto arriva dalla REST API.

Tutti e quattro arrivano come errori JSON-RPC con un header WWW-Authenticate.

Informazioni su OAuth

È implementato un flusso OAuth 2.1 + Dynamic Client Registration affinché i connettori presenti nelle directory possano installare Certivant senza incollare una chiave: il server risponde a una richiesta non autenticata con un puntatore WWW-Authenticate ai metadati della risorsa protetta, e l'accesso, la scelta dell'organizzazione e il consenso avvengono in Certivant. I token che emette si comportano come chiavi API. Le guide qui sopra usano la chiave API bearer, che funziona su ogni host.