> ## Documentation Index > Fetch the complete documentation index at: https://docs.origoid.com/llms.txt > Use this file to discover all available pages before exploring further. # Servidor MCP > `@origoid/mcp-server` — servidor oficial Model Context Protocol. Permite que cualquier LLM compatible con MCP (Claude, Gemini, GPT, Codex, …) lea el spec OrigoID y llame al API directo. El servidor MCP es el punto de integración oficial de OrigoID con asistentes AI de programación y chats que hablan [Model Context Protocol](https://modelcontextprotocol.io). Instálalo una vez en tu cliente y el LLM gana 29 tools: 10 para **construir** una integración OrigoID (gratis, sin API key) y 19 para **ejecutar** calls reales (requieren tu API key). ## Por qué existe Cuando le pides a un asistente AI "agrega validación CURP a mi app Express", quieres que el asistente escriba código contra el contrato OrigoID **actual**, no contra una copia desactualizada que vivía en su training set. El servidor MCP da al LLM acceso vivo y autoritativo a: * el spec OpenAPI completo de cada endpoint, * snippets SDK copy-paste en 8 lenguajes, * la lista completa de códigos `type` de resultado por endpoint, * y la opción de invocar el endpoint cuando ya tengas tu key. Todo excepto las llamadas reales al API es offline y gratis — el LLM puede diseñar y escribir una integración productiva completa sin consumir un solo crédito. ## Compatibilidad MCP es un protocolo abierto adoptado por Anthropic (2024), OpenAI (2025) y Google (2025). El mismo server config funciona en cualquier cliente compliant: * **Claude Desktop** (app macOS) * **Claude Code** (CLI) * **Cursor** * **Windsurf** * **ChatGPT Desktop** * **Codex CLI** * **Gemini CLI / Antigravity** * **Zed** * cualquier otro cliente compatible con MCP ## Instalar con tu AI (atajo) La mayoría de las veces puedes simplemente pedirle a tu asistente AI que lo instale por ti. Copia uno de los prompts de abajo en el chat de tu cliente — el LLM editará el archivo de config correcto (y correrá el comando CLI cuando aplique). **Importante:** los clientes de escritorio (Claude Desktop, Cursor, Windsurf) necesitan reiniciarse después de editar la config; el AI no puede hacerlo por ti. Cierra la app y reábrela. **Convención de rutas:** el atajo `~/` significa el home del usuario en **macOS y Linux** (`/Users//...` y `/home//...` respectivamente). En **Windows**, reemplaza `~/` por `%USERPROFILE%\` (CMD) o `$HOME\` (PowerShell). La config de Claude Desktop usa una ruta `%APPDATA%` específica de Windows, detallada abajo. ### Claude Code (CLI) ```text theme={null} Corre en mi terminal: claude mcp add origoid --env ORIGOID_API_KEY= -- npx -y @origoid/mcp-server Luego verifica con: claude mcp list ``` Funciona idéntico en macOS, Linux y Windows. ### Claude Desktop ```text macOS theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi Claude Desktop. Edita: ~/Library/Application Support/Claude/claude_desktop_config.json Agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], y env ORIGOID_API_KEY=. Recuérdame cerrar y reabrir Claude Desktop (Cmd+Q primero). ``` ```text Windows theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi Claude Desktop. Edita: %APPDATA%\Claude\claude_desktop_config.json Agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], y env ORIGOID_API_KEY=. Recuérdame cerrar y reabrir Claude Desktop. ``` ```text Linux theme={null} Claude Desktop no se distribuye oficialmente para Linux hoy. Usa Claude Code (CLI) — funciona idéntico. Ver el snippet de arriba. ``` ### Cursor ```text macOS / Linux theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi Cursor. Edita ~/.cursor/mcp.json y agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Recuérdame recargar Cursor. ``` ```text Windows theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi Cursor. Edita %USERPROFILE%\.cursor\mcp.json y agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Recuérdame recargar Cursor. ``` ### Windsurf ```text macOS / Linux theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi Windsurf. Edita ~/.codeium/windsurf/mcp_config.json y agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Recuérdame recargar Windsurf. ``` ```text Windows theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi Windsurf. Edita %USERPROFILE%\.codeium\windsurf\mcp_config.json y agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Recuérdame recargar Windsurf. ``` ### Codex CLI ```text macOS / Linux theme={null} Agrega el servidor MCP de OrigoID (@origoid/mcp-server) a mi config de Codex. Edita ~/.codex/config.toml y agrega: [mcp_servers.origoid] command = "npx" args = ["-y", "@origoid/mcp-server"] [mcp_servers.origoid.env] ORIGOID_API_KEY = "" ``` ```text Windows theme={null} Agrega el servidor MCP de OrigoID (@origoid/mcp-server) a mi config de Codex. Edita %USERPROFILE%\.codex\config.toml y agrega el mismo bloque TOML del ejemplo macOS / Linux. ``` ### Gemini CLI / Antigravity ```text macOS / Linux theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi config de Gemini. Edita ~/.gemini/settings.json y agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. ``` ```text Windows theme={null} Instala el servidor MCP de OrigoID (@origoid/mcp-server) en mi config de Gemini. Edita %USERPROFILE%\.gemini\settings.json y agrega "origoid" en mcpServers con command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. ``` Si prefieres configurarlo manualmente, los snippets por cliente están abajo. ## Instalación No instalas el paquete manualmente — tu cliente MCP lo lanza on demand vía `npx`. Elige el snippet de tu cliente: ### Claude Code ```bash theme={null} claude mcp add origoid \ --env ORIGOID_API_KEY=tu_api_key \ -- npx -y @origoid/mcp-server ``` ### Claude Desktop Edita `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o `%APPDATA%\Claude\claude_desktop_config.json` (Windows) y agrega: ```json theme={null} { "mcpServers": { "origoid": { "command": "npx", "args": ["-y", "@origoid/mcp-server"], "env": { "ORIGOID_API_KEY": "tu_api_key" } } } } ``` Reinicia Claude Desktop. ### Cursor Edita `~/.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "origoid": { "command": "npx", "args": ["-y", "@origoid/mcp-server"], "env": { "ORIGOID_API_KEY": "tu_api_key" } } } } ``` ### Windsurf Edita `~/.codeium/windsurf/mcp_config.json` con el mismo bloque `mcpServers.origoid` de arriba. ### ChatGPT Desktop Abre **Settings → Tools → Model Context Protocol** y pega el bloque `mcpServers.origoid` en el editor de config. ### Codex CLI Edita `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.origoid] command = "npx" args = ["-y", "@origoid/mcp-server"] [mcp_servers.origoid.env] ORIGOID_API_KEY = "tu_api_key" ``` ### Gemini CLI / Antigravity Edita `~/.gemini/settings.json`: ```json theme={null} { "mcpServers": { "origoid": { "command": "npx", "args": ["-y", "@origoid/mcp-server"], "env": { "ORIGOID_API_KEY": "tu_api_key" } } } } ``` ### Cualquier otro cliente MCP Usa: * **Command:** `npx` * **Args:** `-y @origoid/mcp-server` * **Env:** `ORIGOID_API_KEY=` El servidor habla MCP sobre el transport estándar stdio. ## API key opcional Si no defines `ORIGOID_API_KEY`, el servidor arranca en **modo docs-only**. Las 10 tools de documentación funcionan normalmente; las 19 tools de API devuelven un error claro si las invocan. Este es el modo correcto para la fase de diseño — el LLM puede describir, scaffold, y escribir tu integración sin que tengas cuenta todavía. ## Tools ### Tools de docs (sin API key, sin créditos) | Tool | Qué devuelve | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_endpoints({domain?})` | Catálogo de cada operación con `operationId`, método, path, y dominio. Filtro opcional por dominio (`renapo`, `sat`, `imss`, `ine`, `compliance`, `biometrics`, `email`, `documents`, `auth`). | | `get_endpoint({operationId})` | Operación OpenAPI completa: descripción, request schema, response examples para cada código `type`, costo en créditos. | | `get_sdk_example({operationId, language})` | Snippet copy-paste. Lenguajes: `curl`, `javascript`, `typescript`, `python`, `php`, `go`, `java`, `ruby`, `csharp`. | | `get_response_types({operationId})` | Cada `type` posible del endpoint con un sample envelope — alimenta tu lógica `switch`/`match`. | | `get_api_overview()` | El `info.description` completo del spec: autenticación, contrato envelope, headers rate-limit, convenciones de lenguaje, política image processing, y todos los catálogos (CURP status, IMSS modalities, SAT lists, OFAC lists, CFDI effects). | | `search_docs({query})` | Búsqueda free-text en summaries, descriptions y examples. | | `validate_envelope_shape({envelopeJson})` | Checker offline — ¿el JSON cumple el contrato canónico `Envelope`? Útil para unit-test de un parser custom. | | `get_typescript_types({operationId})` | Archivo `.ts` self-contained con interfaces `Request`, `Type` (union), `Data`, y `Envelope`. Pega directo en tu proyecto — no requiere instalar el SDK. | | `get_pydantic_model({operationId})` | Archivo `.py` self-contained con clases Pydantic v2 (`Request`, `Type` Literal, `Data`, `ErrorDetail`, `Envelope`). Única dep runtime: `pydantic>=2`. | | `get_full_integration_starter({scenario})` | Proyecto multi-file completo listo para que el usuario (o su asistente AI) lo deje en una carpeta y corra. Scenarios: `express-curp` (Node + Express 5), `fastapi-curp` (Python + FastAPI async), `go-cli-curp` (Go CLI). Cada uno maneja todos los `type` codes con HTTP / exit codes idiomáticos. | ### Tools de API (requieren `ORIGOID_API_KEY`) Una por endpoint. Calls van vía el SDK oficial `@origoid/sdk` a `https://api.origoid.com`. Cada call exitoso consume créditos según la [página de créditos](/es/credits). | Tool | Endpoint | | -------------------------- | ----------------------------------------------------- | | `issue_token` | `POST /auth/token` | | `validate_curp` | `POST /mex/renapo/v1/curp-validations` | | `lookup_curp` | `POST /mex/renapo/v1/curp-lookups` | | `validate_rfc` | `POST /mex/fiscal/v1/rfc-validations` | | `extract_csf` | `POST /mex/fiscal/v1/csf-extractions` | | `validate_cfdi` | `POST /mex/fiscal/v1/cfdi-validations` | | `lookup_nss` | `POST /mex/social-security/v1/imss-nss-lookups` | | `get_employment_status` | `POST /mex/social-security/v1/imss-employment-status` | | `validate_voter_list` | `POST /mex/id/v1/voter-list-validations` | | `extract_voter_id_data` | `POST /mex/id/v1/voter-id-extractions` | | `extract_qr_data` | `POST /mex/id/v1/qr-extractions` | | `search_sat_69` | `POST /mex/compliance/v1/sat-69-searches` | | `search_sat_69b` | `POST /mex/compliance/v1/sat-69b-searches` | | `search_ofac` | `POST /global/compliance/v1/ofac-searches` | | `search_peps` | `POST /mex/compliance/v1/peps-searches` | | `match_faces` | `POST /global/biometrics/v1/face-matches` | | `check_liveness` | `POST /global/biometrics/v1/liveness-checks` | | `validate_email` | `POST /global/email/v1/email-validations` | | `extract_proof_of_address` | `POST /mex/documents/v1/proof-of-address-extractions` | Cada tool de API devuelve el envelope completo como JSON string para que el LLM tenga acceso a `status`, `type`, `data`, `errors[]`, y el `transactionId` (útil para tickets de soporte). ## Sesiones típicas ### Integración a nivel snippet > Agrega validación CURP a mi API Express. Usa el MCP de OrigoID para > verificar el schema y dame un handler TypeScript que cubra todos > los tipos de resultado. El LLM internamente llama: 1. `list_endpoints({domain: "renapo"})` — encuentra `validateCurp` 2. `get_endpoint({operationId: "validateCurp"})` — lee el request schema y cada response example 3. `get_response_types({operationId: "validateCurp"})` — obtiene los 10 códigos `type` posibles para que el switch generado esté completo 4. `get_sdk_example({operationId: "validateCurp", language: "typescript"})` — saca un snippet copy-paste Luego escribe el handler. Nada de eso consumió créditos. Cuando dices "ahora pruébalo", el LLM llama `validate_curp({curp: "..."})` — esa única call es facturada. ### Proyecto completo (un prompt → repo corriendo) > Crea un proyecto completo Express + TypeScript que valida CURPs > contra OrigoID. Usa el integration starter del MCP. El LLM llama `get_full_integration_starter({scenario: "express-curp"})` una sola vez. La tool devuelve seis archivos (`package.json`, `tsconfig.json`, `.env.example`, `.gitignore`, `src/server.ts`, `README.md`), los setup commands, y el run command. El LLM los escribe a disco; tú corres `npm install && npm run dev` y tienes un server funcional en menos de un minuto. Mismo flujo para `fastapi-curp` (Python + FastAPI async) o `go-cli-curp` (Go CLI). ### Integración tipada sin el SDK > Prefiero llamar OrigoID con fetch crudo pero quiero el type safety > del response. Dame los tipos TypeScript de validateCurp. El LLM llama `get_typescript_types({operationId: "validateCurp"})` y recibe un archivo `.ts` self-contained (interfaces `Request`, `Type` union, `Data`, `Envelope`). Para Python, el mismo patrón usa `get_pydantic_model({operationId: "validateCurp"})` y devuelve clases Pydantic v2. ## Comportamiento de costo * **Tools de docs:** costo cero para siempre. Leen del spec OpenAPI empaquetado con el paquete. * **Tools de API:** facturadas según el pricing público. El LLM puede ejecutarlas repetidamente mientras itera; revisa la lista de calls antes de aprobar auto-ejecución. * Recomendamos una API key dedicada para desarrollo asistido por AI, con un pool de créditos separado de tu tráfico productivo. ## Autenticación El servidor lee `ORIGOID_API_KEY` de su entorno. El cliente host MCP es responsable de inyectarla vía el campo `env` en su configuración — nunca como argumento de tool ni dentro del chat. Si accidentalmente pegas tu key en un prompt, rótala. ## Código fuente y versión * npm: [`@origoid/mcp-server`](https://www.npmjs.com/package/@origoid/mcp-server) * GitHub: [github.com/origoid/mcp-server](https://github.com/origoid/mcp-server) El código es público para que puedas auditar cada request que el servidor envía a `https://api.origoid.com`. ## Soporte [support@origoid.com](mailto:support@origoid.com) — bugs, requests de features, o ayuda configurando un cliente que no listamos arriba.