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

Este servidor MCP conecta Veriko a Claude, ChatGPT o Cursor: le pides al asistente, por ejemplo, que compruebe un pago en el CEP de Banxico, que te diga en qué quedó una validación anterior o que descargue el comprobante.

Cubre las 66 operaciones públicas de máquina a máquina. Lo que el asistente puede hacer aquí es exactamente lo que puede hacer una clave de API.

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 clave de API, 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 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,818

~1,616

validations

13

13,583

~3,773

webhooks

10

9,795

~2,721

catalog

4

2,204

~612

beneficiaries

14

10,268

~2,852

usage

7

3,756

~1,043

account

3

1,953

~543

dashboard

1

557

~155

plans

2

1,017

~283

insights

4

2,337

~649

finance

7

6,470

~1,797

billing

1

503

~140

all

66

52,433

~14,565

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.

  • 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.

  • Valida base64 canónico y los límites públicos antes de invocar el SDK: 12 MB para comprobantes OCR (imagen o PDF) 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 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 falla esta comprobación. El workflow de sincronización deja el PR del contrato nuevo como borrador, con el CI corrido y un resumen del cambio en el cuerpo, para revisión antes de aceptarlo.

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 es 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 clave de API.

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 cover read-only, idempotent, open-world, and non-destructive behavior. The description contributes one useful behavioral detail ('sin requerir clave de API'), but does not disclose return format, rate limits, or other traits beyond what annotations provide.

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 that states the core action and resource with no filler. Every word earns its place.

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 zero-parameter, read-only comparison tool with rich annotations, the description is largely sufficient: it states purpose and no-auth access. The main gap is not explaining how it relates to the sibling list tool, which would help an agent choose between them.

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 accepts zero parameters, so there are no parameter semantics to describe and the baseline is 4. The description appropriately adds no parameter details because none exist.

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?

States a specific verb ('Comprara') and resource ('capacidades y precios públicos'), making the comparison purpose clear. Does not name or differentiate from the sibling tool veriko_list_public_plans, so sibling disambiguation is absent.

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?

Adds the context that no API key is required, which implies unauthenticated public use. However, it does not explicitly say when to choose this tool over veriko_list_public_plans or state any exclusions, leaving usage to inference.

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 clave de API.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond those: no API key is required for authentication, which is not captured by any structured field.

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 sentence with no filler; the key distinguishing fact (no API key) is stated immediately. Nothing is redundant or padded.

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 zero-parameter read-only list tool with full annotation coverage and no output schema, the description plus structured fields give an agent enough to invoke it correctly. The one gap is routing relative to the sibling comparison tool, which is left unspecified.

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 takes zero parameters, so the schema has nothing to document and there is no parameter semantics for the description to explain. Baseline 4 applies.

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?

States a specific verb ('Lista') and resource ('planes públicos'), which tells an agent exactly what the tool returns. It does not differentiate from the sibling veriko_get_public_plan_comparison, which also concerns public plans, so the agent gets no help choosing between them.

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?

No when-to-use guidance and no mention of the sibling comparison tool as an alternative. The only implicit condition is that no API key is needed, which is a prerequisite, not a selection rule.

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.8/5.0

Scored across 2 tools

Disambiguation4/5

The two tools are mostly distinct: one lists public plans, the other compares capabilities and prices. However, there is potential overlap since a listing might include the same data, and an agent could be unsure whether to use list or comparison for pricing details.

Naming Consistency5/5

Both tools follow a clear, consistent pattern: a shared 'veriko_' prefix followed by a verb_noun structure (list_public_plans, get_public_plan_comparison). All snake_case and predictable.

Tool Count3/5

With only 2 tools, the set is borderline thin for a public plan API. While the narrow scope may justify a small count, it feels under-provisioned compared to typical 3–15 tool servers.

Completeness4/5

The surface covers listing and comparison of public plans, which likely satisfies the core read-only use case. A minor gap is the absence of a tool to fetch an individual plan’s full details by ID, though agents could work around it using the comparison tool.

Maintenance

ActivityNo data
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • junto-mcp

    vrllrv
    A
    license
    A
    quality
    F
    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
    36 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