Debugg AI

Debugg AI — Servidor MCP

Pruebas de navegador impulsadas por IA a través del Protocolo de Contexto de Modelo. Apúntalo a cualquier URL (o localhost) y describe qué probar: un agente de IA navega por tu aplicación y devuelve aprobado/reprobado con capturas de pantalla.

Configuración

Requiere Node.js 20.20.0 o posterior (requisito transitivo de posthog-node@^5.26.0).

Probar URLs http://localhost:... requiere el binario caddy — check_app_in_browser, probe_page y trigger_crawl tunelizan objetivos de localhost a través de un proxy inverso local de Caddy. Esto se instala automáticamente: la dependencia npm @radically-straightforward/caddy descarga una versión fijada de Caddy para tu plataforma durante npm install/npx — no necesitas instalar nada tú mismo en el caso normal. Ahora es el único binario que descarga este paquete; el cliente de túnel en sí es TypeScript puro — reemplazó al paquete ngrok, que obtenía el agente de ngrok. Si esa descarga nunca se ejecutó (npm install --ignore-scripts, una instalación sin conexión/aislada), apunta CADDY_BIN a tu propia instalación (brew install caddy / apt install caddy / consulta caddyserver.com/docs/install) — su ausencia se manifiesta como un error claro en la primera llamada a una URL de localhost, no como un cuelgue silencioso. Las llamadas a URLs públicas, todas las herramientas que no son de navegador y test_suite {action:"run"} (que usa su propio túnel dedicado y omite Caddy por completo) no lo necesitan de ninguna manera.

Obtén una clave de API en debugg.ai y luego añádela a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "debugg-ai": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

O con Docker:

docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp

El paso npm install del Dockerfile detectaría caddy de la misma manera automática que las instalaciones locales lo hacen, en principio — pero al momento de escribir esto, el Dockerfile no COPY varios directorios que la compilación ahora necesita (handlers, tools, types, config) y todavía referencia un directorio tunnels/ que ya no existe, por lo que una compilación nueva probablemente falle antes de que eso importe. Esa es una brecha preexistente, no relacionada con Caddy. La imagen quinnosha/debugg-ai-mcp actualmente publicada es anterior a la dependencia de Caddy de todos modos — las llamadas a URLs de localhost hacia check_app_in_browser/probe_page/trigger_crawl fallarán con CaddyBinaryNotFoundError dentro de esa imagen hasta que se reconstruya (Dockerfile corregido) y se vuelva a publicar, o CADDY_BIN apunte a una incluida por separado. Las llamadas a URLs públicas, las herramientas que no son de navegador y test_suite {action:"run"} no se ven afectadas de ninguna manera.

Herramientas

El servidor expone 8 herramientas: tres herramientas de Navegador más una herramienta basada en acciones por entidad gestionada. Las herramientas principales son check_app_in_browser (agente de IA completo) y probe_page (sonda de página ligera sin LLM). El resto — project, environment, test_suite, test_case, executions — cada una toma un discriminador action (por ejemplo, {"action":"list"}) que selecciona la operación. Las acciones destructivas de delete requieren confirmación (una solicitud de elicitación donde se admita; de lo contrario, confirm: true).

Navegador

check_app_in_browser

Ejecuta un agente de navegador de IA contra tu aplicación. El agente navega, interactúa e informa con capturas de pantalla. Las URLs de localhost se tunelizan automáticamente a través del servidor de túnel de debugg.

Parámetro	Tipo	Descripción
description	cadena obligatorio	Qué probar (lenguaje natural)
url	cadena obligatorio	URL de destino — http://localhost:3000 se tuneliza automáticamente
environmentId	cadena	UUID de un entorno específico
credentialId	cadena	UUID de una credencial específica
credentialRole	cadena	Elegir una credencial por rol (por ejemplo, admin, guest)
username	cadena	Nombre de usuario para iniciar sesión (efímero — no se persiste)
password	cadena	Contraseña para iniciar sesión (efímera — no se persiste)
loginCredentials	matriz	Cuentas para los inicios de sesión que el agente encuentra durante la tarea — [{username, password, label?}]
useEnvironmentCredentials	booleano	Predeterminado true. false prohíbe autocompletar las credenciales almacenadas del entorno; sin una cuenta nombrada significa no iniciar sesión en absoluto
freshSession	booleano	Predeterminado false. true fuerza un inicio de sesión real en lugar de reutilizar la sesión cálida mantenida para esa cuenta
auth	objeto	Precondición de autenticación — {precondition, entryUrl, deepUrl, environmentId, username, password}
repoName	cadena	Anular el nombre de repositorio git detectado automáticamente (por ejemplo, my-org/my-repo)

Una verificación enfocada por llamada. El agente tiene un presupuesto interno de ~25 pasos; divide las suites más amplias en múltiples llamadas.

Credenciales: pásalas como parámetros, no como prosa

Nombrar una cuenta solo en description no hace que el agente la use — recurre a la credencial almacenada del entorno, y el rechazo de la aplicación a la cuenta incorrecta parece una falla de la aplicación. Cualquier cosa que pases como parámetro supera al valor predeterminado del entorno para cada inicio de sesión en la ejecución, no solo el primero:

• username / password (o credentialId / credentialRole) — la identidad de la ejecución.
• auth.username / auth.password — fija el inicio de sesión de precondición cuando también usas auth.precondition: "login".
• loginCredentials — cuentas para un formulario de inicio de sesión que el agente encuentra a mitad de la tarea. Esta es la opción para flujos como establecer una contraseña → ser redirigido al inicio de sesión → iniciar sesión como la cuenta que acabas de crear, donde dividir en llamadas separadas perdería el estado del navegador.

Establece useEnvironmentCredentials: false cuando una recurrencia silenciosa al usuario de prueba predeterminado invalidaría la verificación.

¿SSO entre dominios? Una ejecución solo escribe credenciales en el host propio de la aplicación y sus subdominios; una página de inicio de sesión en otro dominio se rechaza como offscope_host. Añade el host del proveedor de identidad al authorizedCredentialHosts del entorno (consulta environment).

¿Verificando una página que no necesita inicio de sesión? Pasa useEnvironmentCredentials: false y no nombres ninguna cuenta. Esa combinación significa exactamente lo que dice — no iniciar sesión — y la ejecución omite la autenticación por completo en lugar de buscar un formulario de inicio de sesión. Úsalo para páginas públicas, sitios de marketing, documentación y cualquier cosa previa a la autenticación. También es más rápido: en el valor predeterminado (auto), el agente seguirá un enlace de "Iniciar sesión" fuera de tu página e intentará la cuenta almacenada del entorno antes de evaluar cualquier cosa.

Reutilización de sesiones: por qué una verificación puede informar "sin formulario de inicio de sesión"

Las ejecuciones no inician sesión cada vez. Después de un inicio de sesión verificado, el backend captura la sesión de esa cuenta y la restaura en la siguiente ejecución para la misma identidad, lo que omite el inicio de sesión por completo — por eso una verificación puede legítimamente volver con submitted: false y sin formulario de inicio de sesión: ya estaba autenticada. Una ejecución restaurada se informa en logins con reason: "restored_session", para que puedas distinguirla de una ejecución que genuinamente no encontró ningún formulario.

Las sesiones se clasifican por cuenta, por lo que nombrar una cuenta diferente nunca reutiliza la de otra persona. Dos formas de evitar la reutilización:

• freshSession: true en una sola llamada — inicia sesión de verdad esta vez y luego vuelve a capturar. Úsalo cuando el flujo de inicio de sesión es lo que estás verificando, cuando sospechas que la sesión almacenada está obsoleta o cuando la única ruta de la aplicación entre personas es cerrar sesión.
• Herramienta environment, action: "clearSessions" — invalida las sesiones almacenadas para que las ejecuciones posteriores inicien sesión. Limita con username / credentialId; las limpiezas sin alcance requieren confirmación porque cada cuenta en el entorno se vuelve a autenticar.

Usa action: "sessions" para ver qué tiene actualmente un entorno y si cada una se reutilizaría.

Los resultados informan la identidad realmente utilizada, por lo que una incorrecta es visible en lugar de hacerse pasar por una aplicación rota:

"logins": [
  { "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true },
  { "username": "qatest123@example.com", "source": "env_default", "submitted": false, "authenticated": false,
    "reason": "offscope_host", "detail": "refused to enter credentials on auth.idp.example: not part of this run's scope …" }
],
"credentialWarning": {
  "requested": "qa+invitefix@example.com",
  "used": ["qatest123@example.com"]
}

source es task | explicit | credential_id (una cuenta que nombraste) o env | env_default (la cuenta almacenada del entorno). submitted es verdadero solo cuando las credenciales se escribieron y enviaron realmente; reason dice qué sucedió (por ejemplo, offscope_host, restored_session), y detail, cuando está presente, es una explicación legible por humanos de ello — para un rechazo de offscope_host nombra el host y cómo autorizarlo. credentialWarning aparece solo cuando nombraste una cuenta y se envió realmente un valor predeterminado del entorno para una cuenta diferente — nunca para un inicio de sesión que fue rechazado u omitido. loginError aparece cuando una cuenta nombrada no pudo resolverse y la ejecución se negó a sustituir una diferente.

Cada ejecución exitosa devuelve un bloque browserSession junto con la captura de pantalla — URLs S3 prefirmadas para el HAR capturado (traza de red completa) y el registro de consola (cada mensaje de consola de JS). Úsalos para detectar bucles de reobtención, errores de hidratación y otros problemas de tiempo de ejecución que pasan las verificaciones de tipos y las pruebas unitarias:

"browserSession": {
  "harUrl": "https://...session_18139.har?X-Amz-...",
  "consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
  "recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
  "harStatus": "downloaded",
  "consoleLogStatus": "downloaded",
  "harRedactionStatus": "redacted",
  "consoleLogRedactionStatus": "redacted"
}

Las URLs son S3 prefirmadas de corta duración — vuelve a obtener la ejecución principal mediante executions {action:"get", uuid} para renovarlas. harStatus / consoleLogStatus desambiguan 'downloaded' (URL obtenible), 'not_available' (la página no emitió nada), 'failed' (la captura falló). En una ejecución nueva, las URLs suelen estar null porque la captura se sube de forma asíncrona después de que el agente termina — consulta executions {action:"get", uuid: executionId} hasta que el estado alcance 'downloaded'. Los encabezados de Autorización / Cookie / token/secret/api_key se eliminan en el servidor antes de que los artefactos se persistan.

trigger_crawl

Lanza un rastreo de agente de navegador del lado del servidor para poblar el grafo de conocimiento del proyecto. Las URLs de localhost se tunelizan automáticamente. Devuelve {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} con knowledgeGraph.skipped === false en la ingesta exitosa. crawlSummary y knowledgeGraph contienen solo las claves que los nodos de rastreo/importación del backend informaron — un conteo faltante está ausente, nunca un 0 rellenado. El bloque browserSession (URLs de HAR + registro de consola, con la misma forma que arriba) también está presente en rastreos completados.

probe_page

Sonda de página por lotes ligera sin LLM. Pasa de 1 a 20 URLs; cada una navega, se asienta en el contenido (el DOM se queda en silencio, con límite — nunca en silencio de red, que una aplicación en vivo nunca alcanza) y devuelve el estado renderizado — captura de pantalla + metadatos de página + errores de consola estructurados + resumen de red. Sin bucle de agente, sin costo de LLM, sin aserciones de escenario. Úsalo para "¿acabo de romper /settings?", humo de múltiples rutas después de una refactorización, barridos de CI por PR y verificaciones rápidas de disponibilidad donde el bucle de agente de 60-150 s de check_app_in_browser es excesivo.

Parámetro	Tipo	Descripción
targets	matriz obligatorio	1-20 entradas: [{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	cadena obligatorio	URL pública o localhost (tunelizado automáticamente)
targets[].waitForLoadState	enumeración	'domcontentloaded' (predeterminado, + un asentamiento de contenido con límite) / 'load' (también bloquea en incrustaciones de terceros) / 'networkidle' (aceptado, nunca emitido — la red de un sitio en vivo no se vuelve inactiva)
targets[].waitForSelector	cadena	Selector CSS opcional para esperar después de la navegación
targets[].timeoutMs	número	Tiempo de espera por URL, 1000-30000 (predeterminado 10000)
includeHtml	booleano	Devolver HTML sin procesar en cada resultado (predeterminado falso)
captureScreenshots	booleano	Devolver un PNG por objetivo (predeterminado verdadero)

Todos los objetivos en un lote comparten un túnel de sesión, pero solo los lotes del mismo puerto (o todos públicos) comparten una única ejecución de backend — 5 URLs en un puerto en una llamada es dramáticamente más rápido que 5 llamadas paralelas de una sola URL. Un lote que mezcla múltiples puertos locales se descompone en una ejecución de backend secuencial por grupo de puertos (sigue siendo una llamada, sigue siendo un results[] fusionado en tu orden original, pero N viajes de ida y vuelta de backend en lugar de uno — más lento, no rechazado). El campo error por URL preserva la resiliencia del lote: un solo objetivo fallido no hace fallar a los demás. networkSummary la clave de agregación es origin + pathname — los bucles de re-consulta (?n=0..4 golpeando repetidamente el mismo endpoint) se colapsan en una sola entrada con el conteo, por lo que /api/poll apareciendo con count: 47 es la señal accionable de "bucle de re-consulta infinito" que los usuarios pidieron originalmente.

Presupuesto de rendimiento: <10s para 1 URL, <25s para 20. El puerto muerto de localhost devuelve LocalServerUnreachable en <2s sin quemar una ejecución de workflow.

project

Acción	Parámetros	Resultado
get	{uuid}	Detalle de proyecto curado
list	{q?, page?, pageSize?}	Resúmenes paginados
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	Proyecto creado

El equipo y el repositorio se resuelven por uuid o nombre (coincidencia exacta sin distinción de mayúsculas; NotFound si ninguno, AmbiguousMatch si hay múltiples). No hay update/delete — renombra o elimina un proyecto desde la aplicación web de DebuggAI.

environment

Acción	Parámetros	Resultado
get	{uuid, projectUuid?}	Entorno con credenciales integradas (las contraseñas nunca se devuelven)
list	{projectUuid?, q?, page?, pageSize?}	Entornos paginados, cada uno con un arreglo de credenciales
create	{name, url, description?, projectUuid?, credentials?, authorizedCredentialHosts?}	Entorno creado (opcionalmente siembra credenciales)
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?}	Entorno parcheado; las operaciones de credenciales se ejecutan eliminar → actualizar → agregar
delete	{uuid, projectUuid?, confirm?}	Elimina el entorno (cascada de credenciales) — requiere confirmación
sessions	{uuid, username?, credentialId?}	Sesiones de inicio de sesión capturadas que el entorno mantiene, por cuenta, cada una con su propio isUsable
clearSessions	{uuid, username?, credentialId?, confirm?}	Las invalida para que la próxima ejecución inicie sesión de verdad — las limpiezas sin alcance requieren confirmación

projectUuid se auto-resuelve desde el repositorio git cuando se omite. Las fallas por credencial aparecen en credentialWarnings[] sin bloquear la operación del entorno.

authorizedCredentialHosts lista los hosts donde una ejecución puede ingresar las credenciales de este entorno además del host propio de la aplicación — para SSO entre dominios, agrega el host del IdP aquí (p. ej. ["auth.example.com"]). Solo nombres de host desnudos: sin esquema, ruta, puerto ni comodín (los subdominios del host de la aplicación ya están en alcance). En update reemplaza la lista; [] la limpia. get/list la devuelven cuando el servidor lo soporta. La respuesta hace eco de la lista guardada; si el servidor no la persistió (servidores más antiguos ignoran el campo), el resultado lleva authorizedCredentialHostsWarning: {requested, returned} en lugar de un éxito silencioso.

sessions / clearSessions gestionan las sesiones autenticadas cálidas que el backend reutiliza para omitir el inicio de sesión (ver Reutilización de sesión). El contenido de las sesiones nunca se devuelve — una cookie de sesión es una credencial de portador. clearSessions marca las sesiones como inválidas en lugar de eliminar las filas, para que la reutilización se detenga de inmediato mientras el historial de captura permanece legible.

test_suite

Acción	Parámetros	Resultado
list	{projectUuid|projectName, search?, page?, pageSize?}	Suites paginadas con estado + tasa de aprobación
create	{name, description, projectUuid|projectName}	Suite creada
run	{suiteUuid|(suiteName+project), targetUrl?}	Dispara todas las pruebas de forma asíncrona
results	{suiteUuid|(suiteName+project)}	Suite + resultados por prueba
delete	{suiteUuid|(suiteName+project), confirm?}	Eliminación suave — requiere confirmación

test_case

Acción	Parámetros	Resultado
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	Caso de prueba creado (no se ejecuta automáticamente)
update	{testUuid, name?, description?, agentTaskDescription?}	Caso de prueba parcheado
delete	{testUuid, confirm?}	Eliminación suave — requiere confirmación

executions

Acción	Parámetros	Resultado
get	{uuid}	Detalle completo (nodeExecutions + estado + errorInfo) + artefactos de captura de pantalla/gif
list	{status?, projectUuid?, page?, pageSize?}	Resúmenes paginados

El 404 del backend se manifiesta como isError: true con {error: 'NotFound', message, uuid}. Las credenciales siempre se devuelven sin contraseñas.

Paginación

Cada respuesta list está paginada. Forma de la respuesta:

{
  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
  "<items>": [ ... ]
}

Pasa opcionalmente page (indexado desde 1, predeterminado 1) y pageSize (predeterminado 20, máximo 200; los valores sobredimensionados se recortan). Ninguna respuesta se trunca silenciosamente.

Un get devuelve el único objeto bajo su nombre singular — {project}, {execution}, {project, environment} — sin pageInfo.

Recursos

Junto a las herramientas, el servidor expone las entidades de solo lectura como recursos de MCP para que los clientes puedan navegar y mencionarlos con @ como contexto:

URI	Qué
debugg-ai://projects	Todos los proyectos (primera página)
debugg-ai://environments	Entornos para el proyecto auto-detectado
debugg-ai://executions	Ejecuciones recientes (primera página)
debugg-ai://project/{uuid}	Un proyecto, detalle completo
debugg-ai://environment/{uuid}	Un entorno (credenciales integradas, contraseñas redactadas)
debugg-ai://execution/{uuid}	Una ejecución, detalle completo de nodo + enlaces de artefactos

Las lecturas se envían a los mismos manejadores que las herramientas project / environment / executions, por lo que los datos y la autenticación son idénticos. Los recursos son aditivos — los clientes sin soporte de recursos siguen usando las herramientas.

Invariantes de seguridad

• Las contraseñas son de solo escritura. Nunca aparecen en ningún cuerpo de respuesta de ninguna herramienta.
• Las URL de túnel (*.tunnel.debugg.ai, y la retirada *.ngrok.debugg.ai que las ejecuciones históricas aún referencian) se eliminan de todas las respuestas del agente de navegador, incluido el texto escrito por el agente.
• Los 404 del backend se manifiestan como isError: true con {error: 'NotFound', ...}, nunca como excepciones lanzadas.
• La falta de DEBUGGAI_API_KEY se manifiesta como un error de herramienta estructurado en la primera invocación — el servidor aún registra y lista las herramientas normalmente.

Migración a v6.0.0 (veredictos del backend, sin texto escrito por MCP)

Un veredicto de ejecución es pass | fail | error, con el reason del backend transmitido textualmente. Una ejecución que nunca intentó una prueba lee outcome: null, skipped: true, skipReason.

Eliminado	Reemplazo
success	outcome
failureCategory	outcome + reason
stepsTaken / stepsBudget / stepsRemaining	budget: {maxSteps, usedSteps}
failedNode	errorInfo
get → projects[0] / executions[0] / environments[0] + pageInfo + filter	{project} / {execution} / {project, environment}
message / note en advertencias y resultados	solo campos estructurados

Lista completa: CHANGELOG.md 6.0.0.

Migración a v3.0.0 (herramientas basadas en acciones)

v3 consolidó las 20 herramientas por verbo en 8 herramientas basadas en acciones. Herramienta antigua → nuevo tool {action}:

Eliminado	Reemplazo
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project, delete_project	Eliminadas — usa la aplicación web de DebuggAI
search_environments	environment {action:"get"} / {action:"list"}
create_environment / update_environment / delete_environment	environment {action:"create"|"update"|"delete"}
create_test_suite / search_test_suites / run_test_suite / get_test_suite_results / delete_test_suite	test_suite {action:"create"|"list"|"run"|"results"|"delete"}
create_test_case / update_test_case / delete_test_case	test_case {action:"create"|"update"|"delete"}
search_executions	executions {action:"get"|"list"}
trigger_crawl parámetro headless	Eliminado — siempre sin cabeza

Las acciones delete ahora requieren confirmación (mensaje de elicitación, o confirm: true). Los clientes recogen la nueva superficie al reiniciar MCP.

Migración desde v1.x (cambio disruptivo en v2.0.0)

v2 colapsó una superficie de 22 herramientas a 11. Mapeo de herramienta antigua → herramienta nueva:

Eliminado	Reemplazo
list_projects, get_project	search_projects (modo uuid vs modo filtro)
list_environments, get_environment	search_environments
list_credentials, get_credential	search_environments — credenciales integradas en cada entorno
create_credential	create_environment({credentials: [...]}) siembra, o update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams, list_repos	create_project({teamName, repoName}) — resolución de nombre con manejo de ambigüedad
list_executions, get_execution	search_executions
cancel_execution	Eliminado — el apagado del backend es automático

Cambios en la forma de las respuestas: el campo desnudo count en las respuestas de lista ya no existe — usa pageInfo.totalCount.

Configuración

Variable de entorno	Requerida	Propósito
DEBUGGAI_API_KEY	sí	Clave API del backend. Aliases: DEBUGGAI_API_TOKEN, DEBUGGAI_JWT_TOKEN.
DEBUGGAI_API_URL	no	URL base del backend. Predeterminada a https://api.debugg.ai.
DEBUGGAI_TOKEN_TYPE	no	token (predeterminado) o bearer.
DEBUGGAI_EVAL_TEMPLATE	no	Sobrescribe el slug del workflow de Evaluación de App al que check_app_in_browser envía. Predeterminado a flow/e2es/app-eval. El envío se fija a este slug para que un renombrado de plantilla del backend no pueda romperlo.
LOG_LEVEL	no	error / warn / info (predeterminado) / debug.
POSTHOG_API_KEY	no	Sobrescribe la clave de proyecto de telemetría integrada (p. ej. fork privado).
DEBUGGAI_TELEMETRY_DISABLED	no	Establece a 1 / true / yes / on para deshabilitar la telemetría por completo.

DEBUGGAI_API_KEY=your_api_key

Transporte remoto / HTTP (opcional)

Por defecto, el servidor habla stdio (npx local). Puede ejecutarse en su lugar como un MCP remoto multi-usuario alojado sobre Streamable HTTP sin estado + OAuth:

DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest

Es un Servidor de Recursos OAuth: cada POST /mcp necesita Authorization: Bearer <token>; los tokens faltantes o inválidos reciben un 401 con un WWW-Authenticate que apunta a los metadatos RFC 9728, y los clientes ejecutan el flujo OAuth contra el servidor de autorización anunciado. El portador está limitado a la solicitud — api.debugg.ai lo valida.

Endpoint	Propósito
POST /mcp	MCP Streamable HTTP (protegido por portador)
GET /.well-known/oauth-protected-resource	Metadatos RFC 9728 (descubrimiento del servidor de autorización)
GET /health	Verificación de salud del balanceador de carga / ECS

Variable de entorno	Predeterminada	Propósito
DEBUGGAI_MCP_TRANSPORT	stdio	Establece a http para el transporte remoto
PORT	3000	Puerto de escucha HTTP
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	URL de recurso público de este servidor (RFC 9728 resource)
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	Servidor de autorización anunciado a los clientes
DEBUGGAI_TOKEN_TYPE	token	Establece a bearer para que los tokens OAuth se reenvíen como Authorization: Bearer

Las instalaciones stdio no necesitan ninguna de estas.

Despliegues multi-réplica (go/no-go antes del lanzamiento): el estado del túnel (el túnel de sesión, su instancia de Caddy y su bloqueo de ruta de puerto) está en proceso, claveado por llamador mediante un hash del token de portador — no hay coordinación entre procesos. Ejecutar varias réplicas detrás de un balanceador de carga round-robin simple significa que las llamadas de un llamador pueden aterrizar en diferentes réplicas y acuñar un túnel por réplica que golpean en lugar de uno para toda la sesión (acotado por el número de réplicas, auto-reparación mediante el apagado automático por inactividad de 55 minutos existente — nunca un error de corrección entre sesiones, ya que cualquier llamada de herramienta individual permanece en una réplica durante toda su duración). Para obtener el comportamiento previsto de "un túnel por sesión" en un despliegue HTTP multi-réplica, configura enrutamiento afín a la sesión en el balanceador de carga (sticky/hash consistente claveado en la misma identidad de la que getSessionKey() deriva — en la práctica, el token de portador Authorization del llamador). Ver docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 para el razonamiento completo y la ruta de degradación honesta si esto no está configurado.

Telemetría

El servidor MCP incluye telemetría habilitada por defecto: una clave de proyecto PostHog integrada de solo escritura (phc_*) para que el equipo pueda observar tasas de acierto de caché, cadencia de sondeos, fiabilidad del túnel y otras métricas operativas en toda la base de instalaciones. Eventos capturados:

Evento	Cuándo
tool.executed / tool.failed	Por llamada a herramienta
workflow.executed	Por ejecución del agente de navegador (incluye pollCount, durationMs, finalIntervalMs)
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	Por evento del ciclo de vida del túnel
template.lookup / project.lookup	Acierto/fallo de caché con durationMs en llamadas en frío

Postura de privacidad:

• El ID distintivo es SHA-256(api_key).slice(0, 16) — nunca la clave sin procesar, sin PII.
• Las claves phc_* son de solo escritura por convención de PostHog; seguras para incrustar en el código fuente.
• Establece DEBUGGAI_TELEMETRY_DISABLED=1 para optar por no participar por completo (se resuelve a un proveedor sin operación; ningún evento sale del proceso).

El modo activo se registra al inicio:

Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)

Desarrollo Local

npm install
npm run build
npm run test:e2e        # real end-to-end evals against the backend

El conjunto de evaluación inicia el servidor MCP compilado como subproceso, ejercita cada herramienta contra un backend real y escribe artefactos por flujo en scripts/evals/artifacts/<timestamp>/. Consulta scripts/evals/flows/ para los escenarios individuales.

Registro MCP: debugg-ai-local vs debugg-ai

Este repositorio incluye un .mcp.json que registra un servidor con ámbito de proyecto llamado debugg-ai-local apuntando a node dist/index.js — el código local recién compilado. Solo se activa cuando el directorio de trabajo de Claude Code es este repositorio.

Tus otros proyectos deberían usar el registro debugg-ai con ámbito de usuario que extrae del paquete npm publicado:

npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp

Después de editar código aquí, ejecuta npm run mcp:local (que solo recompila) para que la siguiente invocación de debugg-ai-local recoja tus cambios.

Enlaces

Dashboard · Docs · Issues · Discord

---

Licencia Apache-2.0 © 2025 DebuggAI