Instalación

Conecte cualquier cliente MCP (Claude, Cursor, VS Code, OpenAI Codex, Gemini, Mistral) al servidor MCP de Certivant usando su clave de API de Certivant existente como token Bearer.

El servidor MCP de Certivant habla Streamable HTTP en un único endpoint, POST /mcp, y se autentica con una clave de API de Certivant enviada como token Bearer. No hay que aprovisionar ninguna credencial MCP independiente.

Antes de empezar

Obtenga una clave de API. Créela en el panel, en KYC → Desarrollador (solo Propietario o Administrador). Empieza por kyk_ y se muestra una sola vez; consulte Autenticación.

Concédale los ámbitos adecuados. kyc:read basta para el triaje, la explicación y los informes. Añada kyc:write para enviar formularios, iniciar verificaciones, enviar recordatorios, renovar y enviar datos KYB. kyc:submit para enviar una solicitud al procesamiento. El servidor MCP reenvía su clave tal cual: una herramienta para la que no tenga el ámbito devuelve el propio 403 de la API REST.

Conozca la URL de su servidor. Si Certivant ejecuta el servidor MCP por usted, use el host que le han facilitado. Si lo ejecuta usted mismo, escucha en MCP_PORT (por defecto 3007) y se comunica con la aplicación en CERTIVANT_API_BASE_URL (por defecto http://localhost:3005).

Trate la clave de API de estos archivos de configuración exactamente como una contraseña. Cualquiera que la tenga puede actuar sobre su organización con sus ámbitos, incluido el envío de correos reales a sus clientes.

Ejecute el servidor

Si lo aloja usted mismo junto con el resto de la plataforma:

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

Compruebe que está en marcha. Este endpoint no requiere autenticación a propósito y solo informa de que el proceso está escuchando, nunca de que la API REST esté sana:

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

Funciona con cualquier cliente MCP

El servidor MCP de Certivant sigue el Model Context Protocol abierto, así que no está vinculado a Claude ni a ningún proveedor concreto. Cualquier asistente, editor, CLI o plataforma que hable MCP sobre Streamable HTTP puede usarlo: Claude Desktop y Claude Code, Cursor, VS Code, OpenAI Codex, Google Gemini, Mistral y los nuevos clientes que aparecen constantemente.

Sea cual sea el que use, el esquema es el mismo: apunte el cliente a POST https://your-mcp-host/mcp y envíe su clave de API de Certivant como Authorization: Bearer kyk_…. El resto corresponde al formato de configuración propio de ese cliente. Los más habituales se incluyen a continuación; si el suyo no aparece, use la misma URL y el mismo encabezado en sus ajustes de MCP y funcionará.

Configure un host nativo de MCP

Estos hosts leen un archivo de configuración (o una interfaz de ajustes) y se conectan al servidor por usted. Pegue el endpoint y su clave, y las herramientas aparecerán en el asistente.

Añádalo desde la CLI:

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

Después, compruebe que se ha conectado:

claude mcp list

Edite ~/.cursor/mcp.json (global) o .cursor/mcp.json en el proyecto:

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

Cree .mcp.json en el espacio de trabajo (o añádalo a su mcp.json de usuario). Pida la clave en lugar de guardarla en el repositorio:

{
  "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}"
      }
    }
  }
}

El archivo claude_desktop_config.json de Claude Desktop lanza servidores locales, así que un endpoint HTTP remoto se conecta mediante mcp-remote:

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

Reinicie Claude Desktop después de editar el archivo.

Codex lee ~/.codex/config.toml (o un .codex/config.toml del proyecto en una carpeta de confianza). Añada un servidor Streamable HTTP y tome la clave de una variable de entorno para que no quede almacenada en texto plano:

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

O añádalo desde la 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 envía el valor como Authorization: Bearer <token>. Para un encabezado distinto de Authorization, use http_headers en lugar de bearer_token_env_var.

Añada el servidor en ~/.gemini/settings.json (o en un .gemini/settings.json del proyecto). La clave httpUrl selecciona el transporte Streamable HTTP:

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

Cree su propio agente (APIs y frameworks)

La sección anterior cubre los clientes listos para usar a los que basta apuntar al servidor: Claude, Cursor, VS Code, OpenAI Codex, Gemini CLI. Esta sección es para crear su propio agente en código. Funciona cualquier API de proveedores de modelos que admita MCP remoto (la API Responses de OpenAI, la API Messages de Anthropic, Google Gemini, Mistral), así como los frameworks de agentes independientes del modelo, Vercel AI SDK y LangChain, que exponen las herramientas de Certivant al modelo que use. Todos hablan el mismo transporte Streamable HTTP, así que las mismas herramientas están disponibles en todas partes.

Quién establece la conexión importa.

Conectores alojados por el proveedor: la API Responses de OpenAI, la API Messages de Anthropic, Gemini y el conector de Mistral llaman a su servidor MCP desde su nube. Por tanto, el endpoint debe ser accesible desde internet (un servidor de desarrollo en http://localhost:3007 no funcionará: use su host HTTPS desplegado), y su clave de API llega a ese proveedor.
Clientes de framework: Vercel AI SDK y LangChain se conectan desde su propio código, así que la clave permanece en su proceso y un endpoint local es válido.

En ambos casos, limite la clave al mínimo que necesite el flujo de trabajo, y prefiera una clave solo con kyc:read para ejecuciones autónomas o desatendidas: una clave kyc:write permite a un modelo enviar correos reales a sus clientes sin supervisión humana, a menos que lo controle.

La API Responses acepta un servidor MCP remoto directamente en tools. Obtiene la lista de herramientas del servidor y permite al modelo llamarlas.

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" omite la confirmación humana en todas las herramientas, incluidas las que envían correos a clientes, inician verificaciones o envían recordatorios. Para un uso desatendido, mantenga "always", pase un objeto que apruebe automáticamente solo las herramientas de lectura, o use una clave solo con kyc:read para que no exista ninguna herramienta de escritura que llamar.

La misma entrada de tools funciona desde el SDK de Node y desde una llamada directa a POST https://api.openai.com/v1/responses.

La API Messages de Claude adjunta directamente un servidor MCP remoto; un recordatorio útil de que Certivant es un servidor estándar, no uno específico de 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"],
)

El conector MCP de Anthropic está en beta y cambia activamente: tanto la versión de la cabecera beta como si el servidor se pasa en mcp_servers o dentro del array tools han cambiado. Trate el fragmento como ilustrativo y siga la documentación actual del conector MCP para la forma exacta.

El SDK de Google se conecta mediante una sesión de cliente MCP. Abra una sesión Streamable HTTP contra el servidor y páselo a generate_content como herramienta.

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())

El soporte de MCP en Gemini es experimental y, en el momento de escribir esto, solo llama a herramientas: los recursos y prompts del servidor se ignoran. Las herramientas son la parte que sostiene el flujo, así que en la práctica rara vez supone un problema.

Mistral se conecta mediante un conector que añade en Le Chat o en La Plateforme, en lugar de hacerlo en código. Mistral requiere el mismo transporte Streamable HTTP y la misma autenticación Bearer que ya usa el servidor.

Abra Connectors en Le Chat (o en los ajustes de Studio / Agents).

Añada un conector MCP y pegue la URL de su servidor, https://your-mcp-host/mcp.

Elija HTTP Bearer token como método de autenticación y pegue su clave kyk_…. Mistral también admite OAuth 2.1 para los servidores que lo ofrecen; consulte la nota al final de esta página.

Guarde. Mistral ejecuta el handshake initialize de MCP y lista las herramientas.

El conector de Mistral requiere HTTPS con un certificado TLS válido y un servidor que responda 200 y conteste a la llamada initialize. El host de Certivant desplegado lo cumple; un servidor de desarrollo con HTTP simple o con certificado autofirmado no.

El AI SDK se conecta al servidor y expone sus herramientas a cualquier modelo que use con generateText / streamText: una sola integración, todos los modelos.

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 sigue marcado como experimental_ en el AI SDK.

langchain-mcp-adapters convierte las herramientas del servidor en herramientas de LangChain para cualquier agente de LangChain o LangGraph, con cualquier modelo.

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

Verifique la conexión

Pregunte al asistente «¿qué hay hoy en mi cola de verificación?». Debería llamar a get_todays_queue y devolver recuentos. Si en cambio aparece un error de autenticación, el servidor le indica cuál de los tres modos de fallo se ha producido:

Respuesta	Causa
`Missing Authorization header…`	El host no envía el encabezado en absoluto: revise la escritura y las comillas en la configuración.
`Malformed Authorization header…`	El valor no tiene la forma `Bearer <token>`.
`Bearer token does not look like a Certivant API key…`	Al token le falta el prefijo `kyk_`.
Un 401/403 en una llamada a una herramienta	La clave en sí no es válida, está revocada o no tiene el ámbito. El servidor MCP no valida claves: ese veredicto procede de la API REST.

Los cuatro llegan como errores JSON-RPC con un encabezado WWW-Authenticate.

Acerca de OAuth

Se ha implementado un flujo OAuth 2.1 + Dynamic Client Registration para que los conectores listados en directorios puedan instalar Certivant sin pegar una clave: el servidor responde a una petición no autenticada con un WWW-Authenticate que apunta a sus metadatos de recurso protegido, y el inicio de sesión, la elección de organización y el consentimiento se realizan en Certivant. Los tokens que emite se comportan como claves de API. Las guías anteriores usan la clave de API Bearer, que funciona en todos los hosts.