mcp-unico — Claude Code MCP server: Unico identity checks
Adds Unico verification tools to your agent: CPF/CNPJ checks, document OCR, face matching, PEP and court-record screening. The default endpoint no longer resolves, so it only runs against your own URL.
claude mcp add --env UNICO_CLIENT_ID=<UNICO_CLIENT_ID> --env UNICO_CLIENT_SECRET=<UNICO_CLIENT_SECRET> --env UNICO_ENV=<UNICO_ENV> --env UNICO_BASE_URL=<UNICO_BASE_URL> --env UNICO_AUTH_URL=<UNICO_AUTH_URL> --transport stdio unico -- npx -y @codespar/mcp-unicoWhat mcp-unico does
The npm package is @codespar/mcp-unico. It wraps three Unico products: IDCloud (CPF and CNPJ validation, document field extraction, forgery detection), IDPay (selfie-to-document face comparison and liveness) and IDCheck (PEP, sanctions, Brazilian court records, Unico Score). Webhook management and process status polling come with it. Calling a tool your contract does not cover returns 403.
The server is dead out of the box. At the time of the check neither api.unico.co nor auth.unico.co resolved in DNS, and Unico's current hosts are different ones this code was never written against. The package sits deprecated on npm for reference. Without your own UNICO_BASE_URL and UNICO_AUTH_URL nothing will connect.
Auth is OAuth 2.0 Client Credentials, so bring UNICO_CLIENT_ID and UNICO_CLIENT_SECRET; the bearer token is cached in memory. Credentials belong on the server only, never in a browser or mobile client. Run it with npx, stdio by default, or switch to HTTP with MCP_HTTP=true and MCP_PORT.
What it helps with
- validate a CPF or CNPJ against Receita Federal
- pull typed fields out of a Brazilian ID photo
- match a selfie to the photo on a document
- screen a customer for PEP and sanctions hits
- subscribe a callback URL to verification events
Example prompts for the agent
- Check the CPF in this application and show the Receita Federal result
- Run OCR on
docs/rg.jpgand dump the extracted fields as JSON - Compare
selfie.jpgwith the passport photo and run a liveness check
How to install mcp-unico
Platform CLI
claude mcp add --env UNICO_CLIENT_ID=<UNICO_CLIENT_ID> --env UNICO_CLIENT_SECRET=<UNICO_CLIENT_SECRET> --env UNICO_ENV=<UNICO_ENV> --env UNICO_BASE_URL=<UNICO_BASE_URL> --env UNICO_AUTH_URL=<UNICO_AUTH_URL> --transport stdio unico -- npx -y @codespar/mcp-unicoReplace <…> with your own values
Platform CLI
codex mcp add unico --env UNICO_CLIENT_ID=<UNICO_CLIENT_ID> --env UNICO_CLIENT_SECRET=<UNICO_CLIENT_SECRET> --env UNICO_ENV=<UNICO_ENV> --env UNICO_BASE_URL=<UNICO_BASE_URL> --env UNICO_AUTH_URL=<UNICO_AUTH_URL> -- npx -y @codespar/mcp-unicoReplace <…> with your own values
Config file
{
"mcpServers": {
"unico": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-unico"
],
"env": {
"UNICO_CLIENT_ID": "<UNICO_CLIENT_ID>",
"UNICO_CLIENT_SECRET": "<UNICO_CLIENT_SECRET>",
"UNICO_ENV": "<UNICO_ENV>",
"UNICO_BASE_URL": "<UNICO_BASE_URL>",
"UNICO_AUTH_URL": "<UNICO_AUTH_URL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"unico": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-unico"
],
"env": {
"UNICO_CLIENT_ID": "<UNICO_CLIENT_ID>",
"UNICO_CLIENT_SECRET": "<UNICO_CLIENT_SECRET>",
"UNICO_ENV": "<UNICO_ENV>",
"UNICO_BASE_URL": "<UNICO_BASE_URL>",
"UNICO_AUTH_URL": "<UNICO_AUTH_URL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e UNICO_CLIENT_ID=<UNICO_CLIENT_ID> -e UNICO_CLIENT_SECRET=<UNICO_CLIENT_SECRET> -e UNICO_ENV=<UNICO_ENV> -e UNICO_BASE_URL=<UNICO_BASE_URL> -e UNICO_AUTH_URL=<UNICO_AUTH_URL> unico npx -y @codespar/mcp-unicoReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-unico
How do I install mcp-unico in Claude Code?
Run claude mcp add mcp-unico -e UNICO_CLIENT_ID=<UNICO_CLIENT_ID> -e UNICO_CLIENT_SECRET=<UNICO_CLIENT_SECRET> -- npx -y @codespar/mcp-unico. The longer form with API hosts: `claude mcp add --env UNICO_CLIENT_ID=<UNICO_CLIENT_ID> --env UNICO_CLIENT_SECRET=<UNICO_CLIENT_SECRET> --env UNICO_ENV=<UNICO_ENV> --env UNICO_BASE_URL=<UNICO_BASE_URL> --env UNICO_AUTH_URL=<UNICO_AUTH_URL> --transport stdio unico -- npx -y @codespar/mcp-unico`.
What does mcp-unico do?
It exposes Unico identity tools to the agent: CPF/CNPJ checks, document OCR, face biometrics, liveness, PEP and watchlist screening, court-record search and webhook calls.
Why does the server fail to connect?
Both api.unico.co and auth.unico.co fail DNS resolution and the package is deprecated. If you have a live endpoint, set it in UNICO_BASE_URL and UNICO_AUTH_URL.
