Skip to main content
Glama
veriko-mx-labs

io.github.veriko-mx-labs/veriko

Official
by veriko-mx-labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Veriko MCP

Valida una transferencia SPEI sin salir del editor. Este servidor MCP conecta Veriko a Claude, ChatGPT o Cursor: le pides al asistente que compruebe un pago contra el CEP de Banxico, que te diga en qué quedó una validación anterior o que te baje el comprobante, y responde con el dato, no con una sugerencia de curl.

Cubre las 66 operaciones públicas de máquina a máquina. No incorpora ninguna operación de cookie, sesión o administración: lo que el asistente puede hacer aquí es exactamente lo que puede hacer una clave de API.

Estado: 0.1.0, preparado y sin publicar. El repositorio y los contratos ya son públicos. La publicación del paquete y el alta en el MCP Registry las hace Veriko; hasta entonces se usa desde este repositorio.

Probarlo ahora

Requiere Node.js 20 o posterior.

git clone https://github.com/veriko-mx-labs/veriko-mcp.git
cd veriko-mcp
npm ci
npm run build

Queda un servidor ejecutable en dist/index.js. Para verlo responder sin API key, el perfil de planes públicos no necesita credenciales:

VERIKO_MCP_PROFILE=plans VERIKO_MCP_MAX_RISK=read node dist/index.js

El proceso se queda esperando mensajes MCP por stdin; lo normal es que lo arranque tu cliente, no tú. Esta es la configuración del host, con la ruta absoluta a la copia que acabas de construir:

{
  "mcpServers": {
    "veriko": {
      "command": "node",
      "args": ["/ruta/a/veriko-mcp/dist/index.js"],
      "env": {
        "VERIKO_API_KEY": "veriko_...",
        "VERIKO_MCP_PROFILE": "core",
        "VERIKO_MCP_MAX_RISK": "write"
      }
    }
  }
}

La clave se obtiene en app.veriko.mx. Nunca se pasa como argumento de una herramienta: el servidor sólo la lee de VERIKO_API_KEY, de modo que un texto inyectado en una página que el modelo esté leyendo no puede pedírsela.

Related MCP server: commerce-validators

Lo que consume cuota

veriko_validate_direct y veriko_validate_ocr consumen cuota del plan y se descuentan al aceptar la petición. Lo dice su propia descripción, porque quien las invoca es un modelo y quien paga es una persona: un bucle de un agente puede vaciar una cuota mensual en minutos. El resto del catálogo consulta, exporta o descarga sin consumir validaciones.

Perfiles

VERIKO_MCP_PROFILE acepta core, all, una familia o varias familias separadas por coma.

Perfil

Herramientas anunciadas

core

validar, listar, consultar y descargar CEP

validations

ciclo completo de validaciones

webhooks

endpoints y entregas

catalog

bancos, BIN y estado de Banxico

beneficiaries

lista e importación masiva

usage

consumo, límites y exportación

account

perfil y política de reintentos

dashboard

resumen operativo

plans

planes públicos

insights

métricas agregadas

finance

resúmenes, vistas previas y descargas

billing

suscripción activa

all

las 66 operaciones disponibles

El perfil decide qué familias ve el modelo. El riesgo se controla de forma independiente con VERIKO_MCP_MAX_RISK:

  • read: sólo consultas y descargas;

  • write (predeterminado): incluye validaciones y cambios normales;

  • destructive: agrega eliminaciones, cancelaciones, rotación de secretos y la confirmación de importaciones.

Lo que cuesta anunciar cada perfil

Anunciar una herramienta gasta contexto antes de que el modelo llame a ninguna. Estas cifras salen del propio servidor: bytes de la respuesta tools/list, con npm run measure:catalog. Los tokens son una estimación a 3.6 bytes por token, no una tokenización real, y sirven para comparar perfiles entre sí.

Perfil

Herramientas

Bytes de tools/list

Tokens estimados

core

5

5,617

~1,560

validations

13

13,272

~3,687

webhooks

10

9,716

~2,699

catalog

4

2,204

~612

beneficiaries

14

10,060

~2,794

usage

7

3,756

~1,043

account

3

1,953

~543

dashboard

1

558

~155

plans

2

1,007

~280

insights

4

2,365

~657

finance

7

6,470

~1,797

billing

1

503

~140

all

66

51,854

~14,404

Medido con Node 22 y riesgo destructive, para no ocultar herramientas. all cuesta 9.2 veces lo que core; por eso el perfil predeterminado es core y se amplía por familia cuando hace falta.

Arquitectura

  • Usa el SDK oficial de JavaScript como única capa de transporte hacia la API. El código lo importa mediante @veriko-mx/sdk-runtime, un alias estable que permite cambiar la fuente de distribución sin reescribir el servidor.

  • El SDK runtime viaja incluido en el tarball del MCP. El lockfile verifica el asset de origen durante el build y los consumidores no dependen de que esa URL siga disponible o conserve su contenido.

  • No acepta la clave de API como argumento de ninguna herramienta; sólo lee VERIKO_API_KEY del entorno.

  • Anuncia herramientas según perfil y riesgo, pero conserva adaptadores para las 66 operaciones.

  • Las descargas se devuelven como recursos veriko://artifact/...; nunca como base64 dentro de texto ni como escrituras automáticas en el workspace.

  • Las cinco operaciones idempotentes reciben una clave estable derivada de la operación y los argumentos cuando el integrador no proporciona una.

  • Valida base64 canónico y los límites públicos antes de invocar el SDK: 12 MB para imágenes OCR y 20 MB para importaciones de beneficiarios. El transporte stdio admite completa una importación máxima.

  • Los errores usan error.code, estado, puntero, requestId y retryAfter cuando existen; el texto traducible de la API no se usa como contrato.

Idempotencia

Si se pasa idempotencyKey, se conserva. Si falta, el servidor calcula veriko_mcp_v1_<sha256> sobre el operationId y los argumentos canónicos. En entradas binarias usa el hash del contenido, no una ruta local. La misma acción produce la misma clave; cambiar un dato relevante produce otra.

Desarrollo

npm install
npm run check
npm run check:surface
npm run measure:catalog

check:surface compara el catálogo completo contra el spec público filtrado del SDK y fija su SHA-256. Una operación nueva, retirada o escondida, un esquema de autenticación distinto de la clave de API o cualquier cambio contractual deja el workflow de sincronización en rojo para revisión; no existe known_gaps ni auto-merge.

La API real no se usa en las pruebas. test/server.test.ts conecta cliente y servidor MCP en memoria con un SDK falso.

Transportes

La entrada publicada será stdio. El núcleo vive en createVerikoServer() y no depende del transporte, de modo que un futuro Streamable HTTP puede reutilizar catálogo, políticas, errores y recursos. Un endpoint remoto requerirá autenticación por usuario y no se presentará como equivalente al paquete local.

Seguridad

Consulta SECURITY.md. Nunca abras issues con claves de API, payloads reales, comprobantes, números de cuenta o respuestas sin sanitizar.

Licencia

MIT.

Available Tools

2 tools
veriko_get_public_plan_comparisonComparar planes públicosA
Read-onlyIdempotent

Compara capacidades y precios públicos sin requerir API key.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the description's job is reduced. It adds one useful fact: no API key is needed. This does not contradict annotations, but it adds minimal extra context beyond what structured data already provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no wasted words. It states the action, the object, and a key constraint, achieving maximum clarity in minimal space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless tool with rich annotations, the description adequately conveys the tool's purpose and access requirement. While it doesn't specify the output format, the absence of parameters and the comparative nature of the task make the description sufficiently complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema fully covers them (100% coverage). The description adds no parameter-specific details because there are none to explain, which meets the baseline for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool compares public plan capabilities and prices, using a specific verb ('compares') and resource ('public plans'). It differentiates from the sibling 'list' tool by implying comparison rather than listing, though it doesn't explicitly name the alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes that no API key is required, which is a usage condition, but it does not explicitly state when to use this tool versus the sibling 'veriko_list_public_plans'. The usage context is implied by the word 'compare' rather than explicitly contrasted with listing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

veriko_list_public_plansListar planes públicosA
Read-onlyIdempotent

Lista los planes públicos sin requerir API key.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the fact that no API key is required, which is a meaningful auth-related behavior not present in annotations. However, it does not disclose other behaviors such as pagination, result format, or any rate limits, leaving some gaps. With annotations carrying the safety information, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that starts with the action and the object. There is no filler or redundant information; every word earns its place. It is appropriately sized for a trivial parameterless list operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, no output schema, and annotations cover safety, the description is complete for an agent to call it correctly. It states what the tool returns (public plans) and the key prerequisite (no API key required). Nothing essential is missing, and the sibling distinction is not critical given the different nature of the tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there are no parameter semantics to elaborate on. The schema coverage is 100% because the schema is empty and additionalProperties is false. The baseline for zero parameters is 4, and the description adds no unnecessary parameter information. This is sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Lista' (lists) and the resource 'planes públicos' (public plans), making the purpose unambiguous. It is implicitly distinct from the sibling tool, which is about comparison, but the description does not explicitly name the alternative or differentiate itself. It's specific and clear enough to be understood on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling 'veriko_get_public_plan_comparison'. The phrase 'sin requerir API key' is a prerequisite, not a usage condition. There is no mention of scenarios where one might prefer this tool over another, so an agent would have to infer the appropriate context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedveriko_get_public_plan_comparison
    • First observedveriko_list_public_plans
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one lists all public plans, the other compares plans' capabilities and prices. There is no realistic confusion between retrieving a list and generating a comparison.

Naming Consistency5/5

Both tool names follow the same veriko_<verb>_<noun> snake_case pattern, using intuitive verbs 'list' and 'get'. The naming is perfectly consistent across the small set.

Tool Count3/5

Two tools is on the thin side for a standalone server, though the narrow public-plan browsing/comparison scope makes the count understandable. The server feels minimal but not unreasonable.

Completeness4/5

The server covers the core public-plan workflow: discover plans and compare them. Minor gaps such as fetching details for a single plan or richer pricing breakdowns could exist, but they are not obvious blockers for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • junto-mcp

    vrllrv
    A
    license
    A
    quality
    D
    maintenance
    Create Pix charges (Woovi/OpenPix) · List payments & check status · Refund transactions · Multi-provider routing · Daily/per-tx spending limits · Human-in-the-loop confirmation · JSONL audit trail
    7
    31 npm
    MIT

  • sat69-mcp

    edbror
    A
    license
    A
    quality
    B
    maintenance
    Enables querying Mexico's SAT public lists to verify RFCs in bulk, search by business name, and obtain tax risk verdicts such as critical, high, medium, low, or clean.
    6
    MIT