> ## 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. # MCP server > `@origoid/mcp-server` — official Model Context Protocol server. Lets any MCP-capable LLM (Claude, Gemini, GPT, Codex, …) read the OrigoID spec and call the API directly. The MCP server is OrigoID's official integration point for AI coding assistants and chat clients that speak the [Model Context Protocol](https://modelcontextprotocol.io). Install it once in your client and the LLM gains 29 tools: 10 for **building** an OrigoID integration (free, no API key needed) and 19 for **running** real calls (require your API key). ## Why it exists When you ask an AI assistant to "add CURP validation to my Express app," you want the assistant to write code against the current OrigoID contract, not an outdated copy of it that lived in its training set. The MCP server gives the LLM live, authoritative access to: * the full OpenAPI spec for every endpoint, * copy-paste SDK snippets in 8 languages, * the complete list of result `type` codes per endpoint, * and the option to actually invoke an endpoint once you provide a key. Everything except the actual API calls is offline and free — the LLM can design and write a full production integration without consuming a single credit. ## Compatibility MCP is an open protocol adopted by Anthropic (2024), OpenAI (2025), and Google (2025). The same server config works in every compliant client: * **Claude Desktop** (macOS app) * **Claude Code** (CLI) * **Cursor** * **Windsurf** * **ChatGPT Desktop** * **Codex CLI** * **Gemini CLI / Antigravity** * **Zed** * any other MCP-capable client ## Install with your AI (shortcut) Most of the time you can just ask your AI assistant to install it for you. Copy one of the prompts below into your client chat — the LLM will edit the right config file (and run the right CLI command where applicable) for you. **Heads-up:** desktop clients (Claude Desktop, Cursor, Windsurf) need to be restarted after the config is edited; the AI cannot do that for you. Quit the app and reopen it. **Path conventions:** the `~/` shorthand means the user's home directory on **macOS and Linux** (`/Users//...` and `/home//...` respectively). On **Windows**, replace `~/` with `%USERPROFILE%\` (CMD) or `$HOME\` (PowerShell). The Claude Desktop config uses a Windows-specific `%APPDATA%` path called out below. ### Claude Code (CLI) ```text theme={null} Run this in my terminal: claude mcp add origoid --env ORIGOID_API_KEY= -- npx -y @origoid/mcp-server Then verify with: claude mcp list ``` Works identically on macOS, Linux, and Windows. ### Claude Desktop ```text macOS theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Claude Desktop. Edit: ~/Library/Application Support/Claude/claude_desktop_config.json Add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], and env ORIGOID_API_KEY=. Then remind me to quit and reopen Claude Desktop (Cmd+Q first). ``` ```text Windows theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Claude Desktop. Edit: %APPDATA%\Claude\claude_desktop_config.json Add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], and env ORIGOID_API_KEY=. Then remind me to quit and reopen Claude Desktop. ``` ```text Linux theme={null} Claude Desktop is not officially distributed for Linux today. Use Claude Code (CLI) — works identically. See the snippet above. ``` ### Cursor ```text macOS / Linux theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Cursor. Edit ~/.cursor/mcp.json and add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Then remind me to reload Cursor. ``` ```text Windows theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Cursor. Edit %USERPROFILE%\.cursor\mcp.json and add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Then remind me to reload Cursor. ``` ### Windsurf ```text macOS / Linux theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Windsurf. Edit ~/.codeium/windsurf/mcp_config.json and add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Then remind me to reload Windsurf. ``` ```text Windows theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Windsurf. Edit %USERPROFILE%\.codeium\windsurf\mcp_config.json and add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. Then remind me to reload Windsurf. ``` ### Codex CLI ```text macOS / Linux theme={null} Add the OrigoID MCP server (@origoid/mcp-server) to my Codex config. Edit ~/.codex/config.toml and add: [mcp_servers.origoid] command = "npx" args = ["-y", "@origoid/mcp-server"] [mcp_servers.origoid.env] ORIGOID_API_KEY = "" ``` ```text Windows theme={null} Add the OrigoID MCP server (@origoid/mcp-server) to my Codex config. Edit %USERPROFILE%\.codex\config.toml and add the same TOML block as the macOS / Linux example. ``` ### Gemini CLI / Antigravity ```text macOS / Linux theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Gemini config. Edit ~/.gemini/settings.json and add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. ``` ```text Windows theme={null} Install the OrigoID MCP server (@origoid/mcp-server) in my Gemini config. Edit %USERPROFILE%\.gemini\settings.json and add "origoid" to mcpServers with command "npx", args ["-y", "@origoid/mcp-server"], env ORIGOID_API_KEY=. ``` If you want to wire it up manually instead, the per-client config snippets are below. ## Install You do not install the package manually — your MCP client launches it on demand via `npx`. Pick the snippet for your client: ### Claude Code ```bash theme={null} claude mcp add origoid \ --env ORIGOID_API_KEY=your_api_key \ -- npx -y @origoid/mcp-server ``` ### Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add: ```json theme={null} { "mcpServers": { "origoid": { "command": "npx", "args": ["-y", "@origoid/mcp-server"], "env": { "ORIGOID_API_KEY": "your_api_key" } } } } ``` Restart Claude Desktop. ### Cursor Edit `~/.cursor/mcp.json`: ```json theme={null} { "mcpServers": { "origoid": { "command": "npx", "args": ["-y", "@origoid/mcp-server"], "env": { "ORIGOID_API_KEY": "your_api_key" } } } } ``` ### Windsurf Edit `~/.codeium/windsurf/mcp_config.json` with the same `mcpServers.origoid` block as above. ### ChatGPT Desktop Open **Settings → Tools → Model Context Protocol** and paste the `mcpServers.origoid` block above into the config editor. ### Codex CLI Edit `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.origoid] command = "npx" args = ["-y", "@origoid/mcp-server"] [mcp_servers.origoid.env] ORIGOID_API_KEY = "your_api_key" ``` ### Gemini CLI / Antigravity Edit `~/.gemini/settings.json`: ```json theme={null} { "mcpServers": { "origoid": { "command": "npx", "args": ["-y", "@origoid/mcp-server"], "env": { "ORIGOID_API_KEY": "your_api_key" } } } } ``` ### Any other MCP client Use: * **Command:** `npx` * **Args:** `-y @origoid/mcp-server` * **Env:** `ORIGOID_API_KEY=` The server speaks MCP over standard stdio transport. ## API key is optional If you do not set `ORIGOID_API_KEY`, the server boots in **docs-only mode**. The 10 documentation tools work as usual; the 19 API tools return a clear error if invoked. This is the right mode for the design phase — the LLM can describe, scaffold, and write your integration without you having an account yet. ## Tools ### Docs tools (no API key, no credits) | Tool | What it returns | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_endpoints({domain?})` | Catalog of every operation with `operationId`, method, path, and domain. Optional filter by domain (`renapo`, `sat`, `imss`, `ine`, `compliance`, `biometrics`, `email`, `documents`, `auth`). | | `get_endpoint({operationId})` | Full OpenAPI operation: description, request schema, response examples for every `type` code, credit cost. | | `get_sdk_example({operationId, language})` | Copy-paste snippet. Languages: `curl`, `javascript`, `typescript`, `python`, `php`, `go`, `java`, `ruby`, `csharp`. | | `get_response_types({operationId})` | Every possible result `type` for the endpoint with a sample envelope — feeds your `switch`/`match` logic. | | `get_api_overview()` | The complete `info.description` from the spec: authentication, envelope contract, rate-limit headers, language conventions, image-processing policy, and all catalogs (CURP status, IMSS modalities, SAT lists, OFAC lists, CFDI effects). | | `search_docs({query})` | Free-text search across summaries, descriptions, and examples. | | `validate_envelope_shape({envelopeJson})` | Offline checker — does the JSON match the canonical `Envelope` contract? Useful for unit-testing a custom parser. | | `get_typescript_types({operationId})` | Self-contained `.ts` file with `Request`, `Type` union, `Data` shape, and `Envelope` interfaces. Paste straight into a project — no SDK import required. | | `get_pydantic_model({operationId})` | Self-contained `.py` file with Pydantic v2 classes (`Request`, `Type` Literal, `Data`, `ErrorDetail`, `Envelope`). Only runtime dep is `pydantic>=2`. | | `get_full_integration_starter({scenario})` | A complete multi-file project the user (or their AI assistant) drops into a folder and runs. Scenarios: `express-curp` (Node + Express 5), `fastapi-curp` (Python + FastAPI async), `go-cli-curp` (Go CLI). Each handles every documented result type with idiomatic HTTP / exit codes. | ### API tools (require `ORIGOID_API_KEY`) One per endpoint. Calls are proxied through the official `@origoid/sdk` to `https://api.origoid.com`. Each successful call consumes credits per the [Credits page](/en/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` | Each API tool returns the full envelope as a JSON string so the LLM has access to `status`, `type`, `data`, `errors[]`, and the `transactionId` (useful for support tickets). ## Typical sessions ### Snippet-level integration > Add CURP validation to my Express API. Use the OrigoID MCP to verify > the schema and give me a TypeScript handler that covers every result > type. The LLM internally calls: 1. `list_endpoints({domain: "renapo"})` — finds `validateCurp` 2. `get_endpoint({operationId: "validateCurp"})` — reads the request schema and every response example 3. `get_response_types({operationId: "validateCurp"})` — gets the 10 possible `type` codes so the generated switch statement is complete 4. `get_sdk_example({operationId: "validateCurp", language: "typescript"})` — pulls a copy-paste snippet It then writes the handler. None of that consumed credits. When you say "now run it", the LLM calls `validate_curp({curp: "..."})` — that single call is billed. ### Whole-project starter (one prompt → runnable repo) > Scaffold a complete Express + TypeScript project that validates CURPs > via OrigoID. Use the integration starter from the MCP. The LLM calls `get_full_integration_starter({scenario: "express-curp"})` once. The tool returns six files (`package.json`, `tsconfig.json`, `.env.example`, `.gitignore`, `src/server.ts`, `README.md`), the setup commands, and the run command. The LLM writes them to disk; you run `npm install && npm run dev` and have a working server in under a minute. Same idea works for `fastapi-curp` (Python + FastAPI async) or `go-cli-curp` (Go CLI). ### Strict-typed integration without the SDK > I'd rather call OrigoID with raw fetch but I want the response type > safety. Give me the TypeScript types for validateCurp. The LLM calls `get_typescript_types({operationId: "validateCurp"})` and gets a self-contained `.ts` file (`Request`, `Type` union, `Data`, `Envelope` interfaces). For Python, the same pattern uses `get_pydantic_model({operationId: "validateCurp"})` and returns Pydantic v2 classes. ## Cost behavior * **Docs tools:** zero cost forever. Read from the OpenAPI spec bundled with the package. * **API tools:** billed per the public pricing. The LLM can run them repeatedly while iterating; review the call list before approving auto-execution. * We recommend a dedicated test key for AI-driven development, with a separate credit pool from your production traffic. ## Authentication The server reads `ORIGOID_API_KEY` from its environment. The host MCP client is responsible for injecting it via the `env` field in its configuration — never as a tool argument and never inside the chat. If you accidentally paste your key into a prompt, rotate it. ## Source and version * npm: [`@origoid/mcp-server`](https://www.npmjs.com/package/@origoid/mcp-server) * GitHub: [github.com/origoid/mcp-server](https://github.com/origoid/mcp-server) The source is public so you can audit every request the server sends to `https://api.origoid.com`. ## Support [support@origoid.com](mailto:support@origoid.com) — bugs, feature requests, or help wiring up a client we don't list above.