MCP server

The MCP server is OrigoID’s official integration point for AI coding assistants and chat clients that speak the Model Context Protocol. 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/<you>/... and /home/<you>/... 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)

Run this in my terminal:
claude mcp add origoid --env ORIGOID_API_KEY=<paste_my_key_here> -- npx -y @origoid/mcp-server
Then verify with: claude mcp list

Works identically on macOS, Linux, and Windows.

Claude Desktop

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=<paste_my_key_here>.
Then remind me to quit and reopen Claude Desktop (Cmd+Q first).

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=<paste_my_key_here>.
Then remind me to quit and reopen Claude Desktop.

Claude Desktop is not officially distributed for Linux today. Use
Claude Code (CLI) — works identically. See the snippet above.

Cursor

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=<paste_my_key_here>. Then remind me to reload Cursor.

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=<paste_my_key_here>. Then remind me to reload Cursor.

Windsurf

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=<paste_my_key_here>. Then remind me to reload
Windsurf.

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=<paste_my_key_here>.
Then remind me to reload Windsurf.

Codex CLI

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 = "<paste_my_key_here>"

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

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=<paste_my_key_here>.

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=<paste_my_key_here>.

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

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:

{
  "mcpServers": {
    "origoid": {
      "command": "npx",
      "args": ["-y", "@origoid/mcp-server"],
      "env": {
        "ORIGOID_API_KEY": "your_api_key"
      }
    }
  }
}

Restart Claude Desktop.

Cursor

Edit ~/.cursor/mcp.json:

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

[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:

{
  "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=<your_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.

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:

list_endpoints({domain: "renapo"}) — finds validateCurp
get_endpoint({operationId: "validateCurp"}) — reads the request schema and every response example
get_response_types({operationId: "validateCurp"}) — gets the 10 possible type codes so the generated switch statement is complete
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
GitHub: 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 — bugs, feature requests, or help wiring up a client we don’t list above.

Get started

Reference

SDKs

Why it exists

Compatibility

Install with your AI (shortcut)

Claude Code (CLI)

Claude Desktop

Cursor

Windsurf

Codex CLI

Gemini CLI / Antigravity

Install

Claude Code

Claude Desktop

Cursor

Windsurf

ChatGPT Desktop

Codex CLI

Gemini CLI / Antigravity

Any other MCP client

API key is optional

Tools

Docs tools (no API key, no credits)

API tools (require `ORIGOID_API_KEY`)

Typical sessions

Snippet-level integration

Whole-project starter (one prompt → runnable repo)

Strict-typed integration without the SDK

Cost behavior

Authentication

Source and version

Support

​Why it exists

​Compatibility

​Install with your AI (shortcut)

​Claude Code (CLI)

​Claude Desktop

​Cursor

​Windsurf

​Codex CLI

​Gemini CLI / Antigravity

​Install

​Claude Code

​Claude Desktop

​Cursor

​Windsurf

​ChatGPT Desktop

​Codex CLI

​Gemini CLI / Antigravity

​Any other MCP client

​API key is optional

​Tools

​Docs tools (no API key, no credits)

​API tools (require ORIGOID_API_KEY)

​Typical sessions

​Snippet-level integration

​Whole-project starter (one prompt → runnable repo)

​Strict-typed integration without the SDK

​Cost behavior

​Authentication

​Source and version

​Support

Why it exists

Compatibility

Install with your AI (shortcut)

Claude Code (CLI)

Claude Desktop

Cursor

Windsurf

Codex CLI

Gemini CLI / Antigravity

Install

Claude Code

Claude Desktop

Cursor

Windsurf

ChatGPT Desktop

Codex CLI

Gemini CLI / Antigravity

Any other MCP client

API key is optional

Tools

Docs tools (no API key, no credits)

API tools (require `ORIGOID_API_KEY`)

Typical sessions

Snippet-level integration

Whole-project starter (one prompt → runnable repo)

Strict-typed integration without the SDK

Cost behavior

Authentication

Source and version

Support