Añadir conectores (MCP) a JMAX

Estándar para añadir un conector a JMAX

Un conector es un servidor MCP: un programa que publica un catálogo de herramientas. JMAX lo arranca, le pregunta qué sabe hacer y registra cada herramienta como si fuera suya. El modelo no distingue una herramienta nativa de una que llegó por un conector.

Añadir un conector no es programar. Es una entrada de JSON, y desde la versión 0.2.5 ni siquiera eso: se hace desde Conectores → ➕ Añadir conector. Este documento describe el estándar que hay detrás, para quien quiera entenderlo, revisarlo o escribirlo a mano.

1. Dónde vive

config/mcp.json, dentro de mcpServers, una entrada por conector:

{
  "mcpServers": {
    "mi-conector": {
      "enabled": true,
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/documentos"]
    }
  }
}

El nombre (mi-conector) no es decorativo: prefija todas sus herramientas. Ese servidor publica read_file y JMAX la registra como mi_conector_read_file (los guiones pasan a guion bajo, y el total se corta a 64 caracteres). Dos conectores distintos pueden publicar search sin chocar.

2. Las tres formas de conectarse

`transport`	Qué es	Campo obligatorio
`stdio`	Un programa que corre en este equipo	`command` (+ `args`, `env`, `cwd`)
`http`	Un servidor remoto por HTTP	`url` (+ `headers`)
`sse`	Igual, con el protocolo antiguo de eventos	`url` (+ `headers`)

Si no se escribe transport, se deduce: hay url → remoto; hay command → programa local.

En Windows, npx, npm, uvx y uv se resuelven solos a su .cmd: no hay que escribirlo.

3. Los secretos NO van en mcp.json

Esta es la regla que no se negocia. Un token escrito dentro de mcp.json se queda ahí en claro, viaja en cada copia de seguridad y sale en cualquier captura de pantalla.

En el JSON va solo el hueco; el valor vive en config/secrets.env:

"headers": { "Authorization": "Bearer ${MI_TOKEN}" }

MI_[CENSURADO]

Cualquier ${VARIABLE} de la ficha se sustituye al arrancar el conector. La pantalla de alta lo hace sola: si pegas una configuración con un token dentro, lo aparta a secrets.env, deja el hueco y te dice dónde lo guardó.

4. Que no nazca invisible: `pistas`

Este es el error que ya costó caro dos veces (con la búsqueda web y con Paint). JMAX tiene cientos de herramientas y no se las manda todas al modelo en cada turno: un selector elige las que parecen venir a cuento. Un conector del que nadie dijo con qué palabras se pide no sale nunca, y el usuario jura que JMAX «no tiene» la herramienta que acaba de instalar.

Por eso cada conector declara las suyas:

"pistas": ["incidencia", "ticket", "jira", "bug"]

Cuando el usuario escriba «créame una incidencia», las herramientas de ese conector viajan en el turno, sí o sí. Las pistas viven en la ficha del conector, no en una tabla del código: el conector se lleva las suyas puestas.

5. Campos opcionales que cambian la experiencia

`titulo` y `description` — cómo se presenta

"titulo": { "es": "Bases de datos · Postgres", "en": "Databases · Postgres" }

Aceptan texto suelto o un objeto con los seis idiomas (es, en, pt, de, it, fr). Sin titulo, la pantalla enseña el nombre técnico.

`ajustes` — el formulario que ve el cliente

Sin esto, configurar un conector es editar args a mano. Con esto, la pantalla pinta un formulario en cristiano:

"ajustes": [
  {
    "clave": "CARPETA_RAIZ",
    "arg": 2,
    "etiqueta": { "es": "Carpeta de trabajo" },
    "ayuda":    { "es": "La carpeta (y sus subcarpetas) que podrá leer." }
  }
]

Dónde se guarda el valor, según lo que declares:

"arg": N → se escribe en args[N].
"arg": N, "parte": "host" → se arma una URI por piezas (host, puerto, usuario, clave, bd). Es lo que permite pedir los datos de una base de datos por separado en vez de una cadena de conexión entera.
sin arg → va a env. Si el hueco en env es ${VAR}, se guarda en secrets.env y nunca se devuelve a la pantalla.

Una clave que se llame TOKEN, PASSWORD, API_KEY, SECRET o CLAVE se trata como secreto automáticamente: el campo sale en blanco y vacío significa «no lo cambies».

`acciones` — botones para lo que no es un ajuste

Vincular una cuenta, emparejar un teléfono, pedir un código:

"acciones": [
  {
    "id": "vincular",
    "etiqueta": { "es": "Vincular cuenta de Microsoft" },
    "herramienta": "outlook_login",
    "abrir": "https://login.microsoft.com/device",
    "ayuda": { "es": "Te doy un código y abro la página: escríbelo allí." }
  }
]

herramienta es la que se ejecuta al pulsar; abrir es la página que se abre al mismo tiempo.

6. Permisos: qué puede hacer sin preguntar

Un conector nuevo hereda las reglas del guardián. Lo que toca dinero, manda mensajes fuera o borra cosas debe pedir confirmación. Se declara en config/jmax.toml:

confirm_tools — herramientas concretas que siempre preguntan.
confirm_patterns — trozos de nombre que disparan la pregunta (send, delete, pay…).
never_confirm — lo que nunca molesta (leer, listar, buscar).

Regla de oro: leer no pregunta, escribir hacia fuera sí.

7. El alta desde la pantalla

Conectores → ➕ Añadir conector. Dos caminos:

Importar. Pegas lo que publica el catálogo. Se entienden las cuatro formas que se ven por ahí, sin recortar nada:

{"mcpServers": {"x": {...}}}     el archivo entero de Claude Desktop
{"x": {...}}                     el mapa suelto
{"command": "npx", ...}          la ficha de un solo servidor
{"name": "x", "command": ...}    la ficha con su nombre dentro

Construir. Un formulario: nombre, cómo se conecta, programa o dirección, variables, título y las palabras con las que se lo pedirás.

En ambos casos, «Revisar» no escribe nada: dice cómo se va a llamar, qué secretos va a apartar y qué falta, antes de tocar el disco. Al añadir, el conector arranca en el acto y la pantalla dice cuántas herramientas trajo o por qué no pudo.

8. Comprobaciones antes de darlo por bueno

Arranca: el botón Probar dice cuántas herramientas publica y en cuánto tiempo.
Se ve: sus capacidades aparecen en la tarjeta, en verde.
Se encuentra: pídeselo a JMAX con tus palabras. Si no lo usa, le faltan pistas.
No expone secretos: abre mcp.json y comprueba que solo hay ${VAR}.
Se apaga: desactivarlo retira sus herramientas y mata su proceso; quitarlo lo borra de mcp.json sin tocar los secretos.

9. Dónde buscar conectores hechos

github.com/modelcontextprotocol/servers — los oficiales
github.com/modelcontextprotocol/registry — el registro
github.com/TensorBlock/awesome-mcp-servers
github.com/toolsdk-ai/toolsdk-mcp-registry

10. Resumen para quien tenga prisa

Quiero…	Hago…
Añadir uno de un catálogo	Conectores → ➕ → Importar → pegar → Revisar → Añadir
Añadir uno propio	Conectores → ➕ → Construir
Que JMAX se acuerde de usarlo	Rellenar palabras con las que se lo pedirás
Guardar un token	No lo escribas en el JSON: la pantalla lo aparta sola
Apagarlo un rato	Quitar la casilla «activo»
Quitarlo del todo	Botón Quitar
Que el cliente pueda configurarlo	Añadir un bloque `ajustes` a su ficha

Estándar para añadir un conector a JMAX​

1. Dónde vive​

2. Las tres formas de conectarse​

3. Los secretos NO van en mcp.json​

4. Que no nazca invisible: pistas​

5. Campos opcionales que cambian la experiencia​

titulo y description — cómo se presenta​

ajustes — el formulario que ve el cliente​

acciones — botones para lo que no es un ajuste​

6. Permisos: qué puede hacer sin preguntar​

7. El alta desde la pantalla​

8. Comprobaciones antes de darlo por bueno​

9. Dónde buscar conectores hechos​

10. Resumen para quien tenga prisa​