Instalação

Conecte qualquer cliente MCP — Claude, Cursor, VS Code, OpenAI Codex, Gemini, Mistral — ao servidor MCP da Certivant usando a sua chave de API atual como token Bearer.

O servidor MCP da Certivant usa Streamable HTTP em um único endpoint, POST /mcp, e se autentica com uma chave de API da Certivant enviada como token Bearer. Não há nenhuma credencial MCP separada para provisionar.

Antes de começar

Obtenha uma chave de API. Crie uma no painel, em KYC → Desenvolvedor (somente Owner ou Admin). Ela começa com kyk_ e é exibida uma única vez — veja Autenticação.

Conceda os escopos corretos. kyc:read basta para triagem, explicação e relatórios. Adicione kyc:write para enviar formulários, iniciar verificações, lembrar, renovar e submeter dados de KYB. Use kyc:submit para liberar uma requisição para processamento. O servidor MCP repassa a sua chave sem alterações — uma ferramenta para a qual você não tem o escopo retorna o próprio 403 da API REST.

Saiba a URL do seu servidor. Se a Certivant executa o servidor MCP para você, use o host que foi informado. Se você mesmo o executar, ele escuta em MCP_PORT (padrão 3007) e se comunica com a aplicação em CERTIVANT_API_BASE_URL (padrão http://localhost:3005).

Trate a chave de API nesses arquivos de configuração exatamente como uma senha. Quem a tiver pode agir na sua organização com os escopos dela — inclusive enviar e-mails reais aos seus clientes.

Executar o servidor

Se você hospeda a plataforma por conta própria, junto com o restante dela:

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

Confirme que ele está no ar — este endpoint é intencionalmente sem autenticação e informa apenas que o processo está escutando, nunca que a API REST está saudável:

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

Funciona com qualquer cliente MCP

O servidor MCP da Certivant segue o Model Context Protocol aberto, por isso não está vinculado ao Claude nem a nenhum fornecedor específico. Qualquer assistente, editor, CLI ou plataforma que fale MCP sobre Streamable HTTP pode usá-lo — Claude Desktop e Claude Code, Cursor, VS Code, OpenAI Codex, Google Gemini, Mistral e novos clientes que surgem o tempo todo.

Qualquer que seja o cliente, o formato é o mesmo: aponte-o para POST https://your-mcp-host/mcp e envie a sua chave de API da Certivant como Authorization: Bearer kyk_…. O restante é o formato de configuração próprio de cada cliente. Os mais comuns estão abaixo — se o seu não estiver listado, use a mesma URL e o mesmo cabeçalho nas configurações MCP dele, e vai funcionar.

Configurar um host nativo do MCP

Esses hosts leem um arquivo de configuração (ou uma interface de configurações) e se conectam ao servidor por você. Cole o endpoint e a sua chave, e as ferramentas aparecerão no assistente.

Adicione-o pelo CLI:

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

Depois, verifique se a conexão foi feita:

claude mcp list

Edite ~/.cursor/mcp.json (global) ou .cursor/mcp.json no projeto:

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

Crie .mcp.json no workspace (ou adicione ao seu mcp.json de usuário). Solicite a chave em vez de versioná-la:

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

O claude_desktop_config.json do Claude Desktop inicia servidores locais, por isso um endpoint HTTP remoto é conectado por meio do mcp-remote:

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

Reinicie o Claude Desktop depois de editar o arquivo.

O Codex lê ~/.codex/config.toml (ou um .codex/config.toml do projeto, em uma pasta confiável). Adicione um servidor Streamable HTTP e obtenha a chave de uma variável de ambiente, para que ela não fique armazenada em texto simples:

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

Ou adicione-o pelo CLI:

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

O Codex envia o valor como Authorization: Bearer <token>. Para um cabeçalho diferente de Authorization, use http_headers em vez de bearer_token_env_var.

Adicione o servidor a ~/.gemini/settings.json (ou a um .gemini/settings.json do projeto). A chave httpUrl seleciona o transporte Streamable HTTP:

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

Criar seu próprio agente (APIs e frameworks)

A seção anterior trata dos clientes prontos, para os quais basta apontar o servidor — Claude, Cursor, VS Code, OpenAI Codex, Gemini CLI. Esta seção é para criar o seu próprio agente em código. Toda API de provedor de modelos que suporte MCP remoto funciona — a Responses API da OpenAI, a Messages API da Anthropic, o Google Gemini, o Mistral — assim como os frameworks de agentes independentes de modelo, o Vercel AI SDK e o LangChain, que expõem as ferramentas da Certivant para qualquer modelo que você utilize. Todos falam o mesmo transporte Streamable HTTP, por isso as mesmas ferramentas estão disponíveis em todos os lugares.

Quem faz a conexão importa.

Conectores hospedados pelo provedor — a Responses API da OpenAI, a Messages API da Anthropic, o Gemini e o conector do Mistral chamam o seu servidor MCP a partir da nuvem deles. Por isso, o endpoint precisa estar acessível pela internet (um servidor de desenvolvimento em http://localhost:3007 não vai funcionar — use o seu host HTTPS publicado), e a sua chave de API é enviada a esse provedor.
Clientes de framework — o Vercel AI SDK e o LangChain se conectam a partir do seu próprio código, então a chave permanece no seu processo e um endpoint local é aceitável.

Em qualquer caso, limite a chave ao mínimo que o fluxo de trabalho exige e prefira uma chave somente com kyc:read para execuções autônomas ou sem supervisão — uma chave com kyc:write permite que um modelo envie e-mails reais aos seus clientes, sem ninguém no processo, a menos que você crie uma etapa de aprovação.

A Responses API aceita um servidor MCP remoto diretamente em tools. Ela busca a lista de ferramentas no servidor e permite que o modelo as chame.

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" ignora a confirmação humana em todas as ferramentas, inclusive as que enviam e-mails a clientes, iniciam verificações ou enviam lembretes. Para uso sem supervisão, mantenha "always", passe um objeto que aprove automaticamente apenas as ferramentas de leitura ou use uma chave somente com kyc:read, para que nenhuma ferramenta de escrita exista para ser chamada.

A mesma entrada em tools funciona no SDK do Node e em uma chamada direta POST https://api.openai.com/v1/responses.

A própria Messages API do Claude anexa um servidor MCP remoto diretamente — um lembrete útil de que a Certivant é um servidor padrão, e não específico para o 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"],
)

O conector MCP da Anthropic está em beta e em constante mudança — tanto a versão do cabeçalho beta quanto a forma de passar o servidor (em mcp_servers ou dentro do array tools) já mudaram. Trate o trecho como ilustrativo e siga a documentação atual do conector MCP para o formato exato.

O SDK do Google se conecta por meio de uma sessão de cliente MCP. Abra uma sessão Streamable HTTP com o servidor e passe-a para generate_content como uma ferramenta.

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

O suporte a MCP do Gemini é experimental e, no momento em que esta documentação foi escrita, chama apenas ferramentas — os recursos e prompts do servidor são ignorados. As ferramentas são a parte essencial, por isso isso raramente é um problema na prática.

O Mistral se conecta por meio de um conector que você adiciona no Le Chat ou na La Plateforme, e não em código. O Mistral exige o mesmo transporte Streamable HTTP e a mesma autenticação Bearer que o servidor já usa.

Abra Connectors no Le Chat (ou nas configurações de Studio / Agents).

Adicione um conector MCP e cole a URL do seu servidor, https://your-mcp-host/mcp.

Escolha HTTP Bearer token como método de autenticação e cole a sua chave kyk_…. O Mistral também oferece suporte a OAuth 2.1 para servidores que o disponibilizem — veja a nota no final desta página.

Salve. O Mistral executa o handshake initialize do MCP e lista as ferramentas.

O conector do Mistral exige HTTPS com certificado TLS válido e um servidor que retorne 200 e responda à chamada initialize. O host da Certivant publicado atende a esses requisitos; um servidor de desenvolvimento em HTTP simples ou com certificado autoassinado não atende.

O AI SDK se conecta ao servidor e expõe as suas ferramentas a qualquer modelo que você utilize com generateText / streamText — uma integração, todos os 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

O createMCPClient ainda está marcado com experimental_ no AI SDK.

O langchain-mcp-adapters transforma as ferramentas do servidor em ferramentas do LangChain para qualquer agente LangChain ou LangGraph, em qualquer 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

Verificar a conexão

Pergunte ao assistente "o que há na minha fila de verificação hoje?". Ele deve chamar get_todays_queue e retornar as contagens. Se, em vez disso, aparecer um erro de autenticação, o servidor informa qual dos modos de falha ocorreu:

Resposta	Causa
`Missing Authorization header…`	O host não está enviando o cabeçalho — verifique a grafia e as aspas na configuração.
`Malformed Authorization header…`	O valor não está no formato `Bearer <token>`.
`Bearer token does not look like a Certivant API key…`	O token não tem o prefixo `kyk_`.
Um 401/403 em uma chamada de ferramenta	A própria chave é inválida, foi revogada ou não tem o escopo. O servidor MCP não valida chaves — esse veredito vem da API REST.

Todos os quatro chegam como erros JSON-RPC com o cabeçalho WWW-Authenticate.

Sobre o OAuth

Um fluxo OAuth 2.1 + Dynamic Client Registration está implementado para que conectores listados em diretórios instalem a Certivant sem colar uma chave: o servidor responde a uma requisição sem autenticação com um ponteiro WWW-Authenticate para os seus metadados de recurso protegido, e o login, a escolha da organização e o consentimento acontecem na Certivant. Os tokens emitidos se comportam como chaves de API. Os guias acima usam a chave de API como token Bearer, que funciona em todos os hosts.