MCP Server Guide
Connect AI agents directly to the Singula API using the MCP protocol.
What is MCP?
The Model Context Protocol (MCP) is an open standard that allows AI agents to connect with external tools and data. Singula's MCP server exposes all our verification tools as tools that any compatible agent can use.
Connect
The Singula MCP is a remote server (SSE/HTTP), not a binary you install. In Claude Code you connect it with a single command:
claude mcp add --transport sse singula "https://api.singula.mx/mcp/sse?api_key=sk_live_xxx"With project scope it is shared with your team: committed to .mcp.json.
claude mcp add --transport sse singula --scope project "https://api.singula.mx/mcp/sse?api_key=sk_live_xxx"Manual configuration
If you prefer to edit the file by hand, define the server in .mcp.json (project) or ~/.claude.json (user):
{
"mcpServers": {
"singula": {
"type": "sse",
"url": "https://api.singula.mx/mcp/sse?api_key=${SINGULA_API_KEY}"
}
}
}{
"mcpServers": {
"singula": {
"type": "http",
"url": "https://api.singula.mx/mcp",
"headers": { "Authorization": "Bearer sk_live_xxx" }
}
}
}.claude/settings.json does NOT define MCP servers in Claude Code. Definitions live in .mcp.json (project) or ~/.claude.json (user, via claude mcp add). The mcpServers block inside .claude/settings.json is ignored.
The API key can go in the query (?api_key=) or in the Authorization: Bearer header — both are supported. Replace sk_live_xxx with your real API key from the Singula dashboard.
Troubleshooting
The most common errors when connecting the server, and how to resolve them.
Error POSTing to endpoint (HTTP 400)The server ends up in a failed state. This was a server-side bug, already fixed — not your config. If it persists, contact support.
MCP server "singula" has a "url" but no "type"The server block in .mcp.json is missing "type": "sse" (or "http").
The server does not show upIt was defined in .claude/settings.json instead of .mcp.json or ~/.claude.json. Check with claude mcp list.
⏸ Pending approvalRun claude interactively inside the project to approve the server.
Available Tools
The MCP server exposes the following tools that your AI agent can use:
customer_id OR direct data. Tools marked no customer accept customer_id or the value itself (name, phone, email, tax ID, the file…). For the data tools (checkBlacklist, getJudicialRecords, getJudicialRecordsMoral, getIntelligence, checkEmail, checkPhone and their Premium variants) they are exclusive: sending both or neither returns a clear error; for the file tools (extractDocument, verifyCsf, verifyPoder, extractIne) omit customer_id to go direct, and checkFiel and sendEmailOtp accept at least one. No new tools were added for direct queries: same tools, one more way to call them. A direct call touches no customer and charges exactly the same, and sandbox returns the same mocks.
createCustomer
Create physical person with personal data
createMoralCustomer
Create moral person (company)
getCustomer
Complete customer detail
getCurp
Compute a customer CURP (without a customer: calculateCurp)
validateCurp
Validate a customer CURP against RENAPO (without a customer: validateCurpDirect)
getRfc
Compute a customer RFC (without a customer: calculateRfc)
validateRfc
Validate a customer RFC against SAT (without a customer: validateRfcDirect)
extractIne
no customerINE/IFE OCR + Lista Nominal Vigente
checkBlacklist
no customerSearch sanctions lists (OFAC, EU, UN, UK). For companies, optional legal_name: screens registered name and trade name in a single query
getJudicialRecords
no customerJudicial records for physical person
getJudicialRecordsMoral
no customerJudicial records for moral person. Optional legal_name: registered name and trade name are searched in a single query
getIntelligence
no customerOSINT investigation: social, news, records
createVerification
Create the KYC link (INE/passport + selfie + liveness). Optional: redirect_url, external_id, metadata, document_types, language, expires_in_hours
getVerificationStatus
Session state and verdict: session_status, decision, score, verdict and the full result
getVerificationResult
The same plus the signed photos; the liveness frames only when you ask for them
getVerificationFiles
Signed URLs for the photos of a customer’s latest verification
searchCustomers
Search customers by name or ID
listCustomers
List all customers paginated
extractDocument
no customerRead any document: type, data, checklist and authenticity
verifyCsf
no customerTax certificate cross-checked with the SAT registry
verifyPoder
no customerPower of attorney: attorney, faculties and validity
checkFiel
no customere.firma and CSD certificates of a tax ID, with their validity
sendEmailOtp
no customerSend a 6-digit code and profile the domain
verifyEmailOtp
Verify the 6-digit code that was received
kybExpediente
Cross-check a company’s documents against each other: 26 controls
getVerificationPolicy
How strict your verification is: thresholds, rules, the 26 controls and direct-query retention
updateVerificationPolicy
Move the thresholds, switch a control off, lock the document kit or expire direct queries
checkEmail
no customerVerify email address
checkPhone
no customerVerify phone number
Usage Examples
Once configured, your AI agent can use the tools directly:
Full identity verification
"Create a customer with this data and validate their CURP against RENAPO"
Background check
"Search the judicial records and blacklist for this customer"
Automated due diligence
"Run a full OSINT investigation on customer cus_abc123"
Onboarding a company
Onboard Constructora Demo: verify its tax certificate, read the deed and the power of attorney, check the e.firma and build the dossier.
A one-off query, no customer
Is +52 55 1234 5678 a real phone and whose is it? And check whether Juan Pérez García is on any sanctions list. Do not save him as a customer yet.
Compatible Clients
Singula's MCP server works with any client that supports the protocol:
Claude Desktop
Official Anthropic app
Cursor
AI-powered IDE
Claude Code
Claude CLI for development
Windsurf
IDE with AI agents
Cline
VS Code extension with MCP