Elegir cómo se ejecuta avenir-mcp

avenir-mcp se configura con variables de entorno, definidas en el bloque env de su cliente MCP. La lista completa está en Configuración.

Solo lectura o escrituras

Ajuste	Efecto
nada (por defecto)	12 herramientas de solo lectura; las 13 de escritura no se listan ni se pueden llamar
AVENIR_MCP_WRITE=1	las 25 herramientas; cada herramienta de escritura salvo approve_transactions e import_transactions se previsualiza y confirma

Cualquier otro valor (0, true, yes) mantiene el servidor en solo lectura: solo 1 activa las escrituras.

Ejecutar por stdio (por defecto)

Su cliente arranca avenir-mcp como subproceso y le habla por su entrada y salida estándar. Nada escucha en la red. Es lo que hacen todos los ejemplos de Instalación.

Ejecutar por HTTP

Para un cliente que se conecta a una URL, o para compartir un servidor entre varios clientes de su máquina. Cree primero un token aleatorio largo, que los clientes tendrán que presentar:

export AVENIR_MCP_HTTP_TOKEN=$(openssl rand -hex 32)

Después arranque el servidor:

AVENIR_MCP_TRANSPORT=http \
AVENIR_MCP_HOST=127.0.0.1 \
AVENIR_MCP_PORT=8103 \
YNAB_API_KEY=su-token \
uvx avenir-mcp

Escucha en http://127.0.0.1:8103/mcp (HTTP streamable). Apunte su cliente allí con el token en una cabecera Authorization — con Claude Code:

claude mcp add --transport http avenir-mcp http://127.0.0.1:8103/mcp \
  --header "Authorization: Bearer $AVENIR_MCP_HTTP_TOKEN"

Por HTTP, cada petición se comprueba antes de llegar a una herramienta:

Comprobación	Rechazo	Lo que impide
la cabecera Host designa esta máquina (127.0.0.1, localhost, ::1)	421	una página web que llegara al servidor por DNS rebinding
una cabecera Origin, si existe, es la de este servidor	403	una página de otro sitio, abierta en su navegador
Authorization: Bearer <token>, con AVENIR_MCP_HTTP_TOKEN o el token mostrado al arrancar	401	cualquier otro programa de su máquina o de su red

El token es siempre obligatorio, en solo lectura o no. Si AVENIR_MCP_HTTP_TOKEN no está definido, el servidor crea un token aleatorio al arrancar y lo muestra una vez en stderr; cambia en cada arranque: defina la variable para dar a sus clientes un token que dure.

Manténgalo en su máquina

Mantenga AVENIR_MCP_HOST=127.0.0.1: el tráfico es HTTP simple, sin cifrar. Nunca use 0.0.0.0, nunca publique el puerto en todas las interfaces con Docker o un router, y nunca ponga el servidor en Internet.

Dónde se guarda el diario

Las operaciones aplicadas se registran para poder deshacerlas. Por defecto el diario es $XDG_STATE_HOME/avenir-mcp/journal.jsonl, o ~/.local/state/avenir-mcp/journal.jsonl cuando XDG_STATE_HOME no está definida. Elija otro archivo con AVENIR_MCP_JOURNAL. Vea Diario y deshacer.

Diagnósticos

avenir-mcp escribe sus diagnósticos en stderr — nunca en stdout, que pertenece al protocolo en modo stdio — al nivel de AVENIR_MCP_LOG_LEVEL, WARNING por defecto:

Nivel	Verá
WARNING (por defecto)	solo los problemas
INFO	cada llamada a herramienta y cada petición a YNAB
DEBUG	todo, incluidos los mensajes de la propia biblioteca MCP

Un error esperado (un mes mal formado, una cuenta desconocida) se registra en una línea; un fallo real conserva su traza. El token nunca se registra.

Enviar los logs a un sistema de logs

Para un recolector como Vector, Fluent Bit, Promtail o un agente de Datadog, pida JSON y escriba stderr en un archivo que el recolector lea. En la configuración del cliente:

"command": "/bin/sh",
"args": ["-c", "exec uvx avenir-mcp 2>>\"$HOME/.local/state/avenir-mcp/avenir.log\""],
"env": { "YNAB_API_KEY": "su-token", "AVENIR_MCP_LOG_FORMAT": "json", "AVENIR_MCP_LOG_LEVEL": "INFO" }

Cada línea queda así:

{"time":"2026-09-25T09:12:04.120+00:00","level":"INFO","logger":"avenir_mcp.client","message":"Fetching accounts for plan demo-budget"}

Por HTTP, como servicio, el gestor de servicios guarda stderr: systemd lo envía al journal, launchd al archivo indicado en StandardErrorPath.

Desde el nivel INFO, los mensajes solo contienen identificadores y cantidades — nunca beneficiarios, importes ni nombres de categorías —: los logs pueden salir de su máquina sin sus datos financieros. Deje DEBUG para depurar en local.

Umbral de sugerencias

AVENIR_MCP_CONFIDENCE_THRESHOLD (por defecto 0.90) es la parte del historial de un beneficiario que debe coincidir antes de sugerir una categoría. Bájelo para obtener más sugerencias, acertadas con menos frecuencia. Vea Sugerencias.