Cuando algo no anda
Los problemas que aparecen de verdad, en orden de frecuencia, con la solución concreta. Casi ninguno es un bug: son permisos, sesiones vencidas o el ambiente equivocado.
1. No conecta
Claude dice «Could not connect», «Failed to fetch» o se queda cargando al agregar el conector.
| Causa probable | Cómo lo verificás | Solución |
|---|---|---|
La URL quedó sin /mcp al final. |
Mirá la URL guardada en Ajustes → Conectores. | Tiene que terminar exactamente en /mcp: https://mcp.dynamotech.co/mcp. La raíz sin /mcp es este manual, no el servidor. |
Se pegó http:// en vez de https://. |
Ídem. | Solo https. Claude rechaza conectores sin TLS. |
| La red bloquea el dominio. | Abrí https://mcp.dynamotech.co/ en el navegador: si no carga este manual, es la red. |
Probá con otra red o pedí que habiliten el dominio. |
| El servidor está caído. | Abrí https://mcp.dynamotech.co/healthz: tiene que responder ok. |
Si no responde, avisá — el problema es nuestro, no tuyo. |
2. Dice «unauthorized» o «needs authentication»
Es el estado normal de un conector cuyo login todavía no pasó, o cuya sesión venció. No es un error de configuración.
| Situación | Qué hacer |
|---|---|
| Agregaste el conector y no se abrió ninguna ventana de login. | El navegador bloqueó el pop-up. Permitilo para claude.ai y volvé a apretar Conectar. |
En Claude Code aparece dynamo: needs authentication. |
Escribí /mcp, ponete sobre esa línea y apretá Enter: abre el navegador con la pantalla de login. |
| Funcionaba y de golpe pide login otra vez. | Pasaron ~30 días sin usarlo y la sesión caducó. Volvé a loguearte: son diez segundos y no hay que reconfigurar nada. |
| Te logueás, entra, y a la primera pregunta vuelve a decir unauthorized. | Tu usuario fue desactivado en Dynamo Auth. Eso corta el acceso a todo, no solo al MCP. Pedí que te reactiven. |
| El portal no te deja entrar. | Son las credenciales del portal de Dynamo, no las de Claude — las mismas de Forms y Analytics. Recuperalas ahí, como siempre. |
| Volvés del portal y dice «Tu usuario de Dynamo no tiene acceso a la aplicación MCP». | Entraste bien: lo que falta es el acceso a la app «MCP», que se otorga por proyecto igual que Forms o Analytics. Pedíselo a un administrador de tu proyecto. |
| Volvés del portal y dice «No se pudo completar el inicio de sesión con Dynamo». | El código de un solo uso venció (dura 60 segundos) o ya se usó. Volvé a apretar Conectar en Claude: empieza de cero. |
Ojo con el dominio. La única pantalla legítima que
te pide tu contraseña de Dynamo es la del portal:
auth.dynamotech.co (o auth-qa.dynamotech.co
en QA). El servidor MCP nunca la pide: si una
pantalla en mcp.dynamotech.co te pide la contraseña, es
phishing. No la escribas y avisá.
3. No veo las tools
| Síntoma | Solución |
|---|---|
| El conector figura conectado pero Claude dice que no tiene herramientas de Dynamo. | Reiniciá el cliente (cerrar y abrir la app o la pestaña) y empezá un chat nuevo. La lista de tools se lee al iniciar la conversación: en un chat abierto de antes no aparecen. |
| El conector no aparece en Mobile. | Cerrá y volvé a abrir la app. Verificá en claude.ai que figure Conectado: si allá dice Necesita autenticación, resolvelo allá y el teléfono se sincroniza solo. |
| Aparecen algunas tools pero no la que buscás. | Chequeá el nombre en el índice. Las de analytics llevan prefijo analytics_ en el servidor remoto, aunque en el MCP local se llamen sin prefijo. |
| La tool es nueva — se anunció como desplegada y no aparece. | Reconectar el conector (Reconnect) no alcanza: la lista de tools se negocia una sola vez al iniciar la sesión y el cliente la cachea mientras dure. Cerrá la sesión o el chat del todo y abrí uno nuevo. |
| ¿Cómo sé si el servidor ya la tiene, sin depender de mi caché? | Llamá dynamo_session_status y mirá versiones.forms / versiones.ops: eso consulta el servidor en vivo en cada llamada. El conteo de "N tools" que muestra la UI de /mcp no es una fuente confiable de qué versión corre el servidor. |
Buscás pbix_extract o pbix_propose_spec. |
No existen en el servidor remoto, a propósito: necesitan el archivo .pbix en tu disco. Ver stdio local. |
El servidor responde mcp-disabled. |
El MCP está apagado a propósito (mantenimiento). No es tu sesión: esperá o preguntá. |
4. Una tool dice que no tengo permiso
El servidor nunca actúa con privilegios de servicio: actúa como vos. Lo que Claude ve y toca es exactamente lo que ves y tocás vos en el portal.
| Lo que ves | Qué significa | Qué pedir |
|---|---|---|
Una lista vacía en una tool de auth. |
No es un error. No sos global-admin ni project-admin de ese proyecto, así que no ves ninguna fila. | Project-admin del proyecto que necesitás administrar. |
| «No tenés acceso a este proyecto / dashboard / formulario». | Te falta acceso real en Dynamo Auth, o la app no está habilitada en ese proyecto. | Acceso al proyecto, con esa app habilitada. |
| Las tools de lectura andan y las de escritura fallan. | El conector se autorizó con permiso de solo lectura. | Nada a nadie: borrá el conector y volvé a agregarlo aceptando también el permiso de escritura. |
No podés marcar un ítem de Ops como done. |
Es por diseño: el techo es to_be_human_reviewed. |
Nada. A done lo promueve Daniel. |
5. ¿Estoy en QA o en producción?
Preguntale a Claude «¿en qué ambiente estás?». La tool
dynamo_session_status responde con tu email, el ambiente
y cuándo vence tu sesión — y en producción lo marca como
PROD ⚠️. Si el resultado no es el que esperabas,
estás usando el conector equivocado.
| Ambiente | URL del conector |
|---|---|
| PROD ⚠️ | https://mcp.dynamotech.co/mcp |
| QA | https://mcp-qa.dynamotech.co/mcp |
Antes de cualquier escritura, verificá el ambiente.
Las tools de forms y auth tocan datos y
permisos que los clientes ven. Un
auth_set_user_deactivated en producción deja a esa
persona afuera de todos los productos Dynamo.
6. Una tool cortó la conexión, o dice que la respuesta es demasiado grande
El gateway serializa la respuesta de una tool de una sola pasada. Una respuesta gigante (un form con schemas muy grandes, un listado sin filtrar) puede tardar demasiado o consumir memoria de más — así que, por encima de un límite, el gateway no la envía: te devuelve un error de negocio legible en vez de cortar la conexión en silencio.
| Lo que ves | Qué hacer |
|---|---|
| «La respuesta de "…" ocupa … bytes y excede el límite … Acotá la consulta». | Era una tool de lectura: nada se aplicó. Acotá con filtros, limit/offset, o include_schema:false donde exista, y volvé a pedirlo. |
| «"…" YA SE EJECUTÓ en el servidor y su efecto puede estar aplicado … NO reintentes a ciegas». | Era una tool de escritura. No reintentes de una: verificá primero el estado real (ver la tabla de abajo) y reintentá solo si el cambio no quedó aplicado. |
net::ERR_CONNECTION_CLOSED, sin cuerpo de error. |
Mismo contrato de reintento que arriba, pero sin el mensaje: el gateway no llegó a responder. Verificá el estado real antes de reintentar una escritura. |
| «"…" YA SE EJECUTÓ con esta idempotency_key … no quedó registrado». | Reintentaste con idempotency_key y la escritura ya estaba aplicada, pero su resultado no se guardó. No reintentes con una key nueva: leé el recurso (tabla de abajo). |
IDEMPOTENCY_KEY_REUSED |
Esa key ya se usó con otra tool u otro input. No se ejecutó nada. Para una escritura distinta, usá una key nueva. |
IDEMPOTENCY_IN_PROGRESS |
La ejecución original sigue en curso. Reintentá con la misma key en unos segundos. |
IDEMPOTENCY_OUTCOME_UNKNOWN |
El gateway no sabe cómo terminó la ejecución original; el efecto puede estar aplicado. Verificá (tabla de abajo) y, si no está, reintentá con una key nueva. |
IDEMPOTENCY_NO_IDENTITY / IDEMPOTENCY_UNAVAILABLE |
No se ejecutó nada: la sesión no tiene usuario interno, o el registro no está disponible. Revisá la sesión, o reintentá con la misma key en unos segundos. |
Contrato de reintento para tools de escritura. El efecto en la base (el COMMIT) y el envío de la respuesta HTTP son dos pasos separados — un corte entre medio deja la escritura aplicada aunque el cliente vea un error. Verificá antes de reintentar:
| Dominio | Verificá con |
|---|---|
forms | forms_get_form / forms_list_form_responses — comparar current_version o la fila esperada. |
ops | ops_list (por id si lo tenés) — comparar el campo que la escritura debía cambiar. |
auth | auth_list_users / auth_list_project_members — confirmar el estado esperado. |
| otro dominio | La tool de lectura equivalente de ese dominio — mismo criterio: leé antes de reintentar. |
Reintento seguro con idempotency_key.
Toda tool de escritura acepta el argumento opcional
idempotency_key (un UUID v4 nuevo por intento lógico, el
mismo en sus reintentos). Con la misma key y el mismo input dentro de
24 h, el gateway no vuelve a ejecutar: devuelve el resultado ya
registrado. Garantía: a lo sumo una ejecución por key;
si el gateway no sabe cómo terminó, responde
IDEMPOTENCY_OUTCOME_UNKNOWN en vez de ejecutar de nuevo.
El conector de Claude no la manda solo.
Más detalle para quien integra contra el gateway:
docs/manuals/contrato-de-reintento-del-gateway.md en el repo
(sección «Reintento seguro con idempotency_key»).
Nada de esto lo resolvió
Contá tres cosas y se diagnostica en un minuto:
qué cliente usás (web, Desktop, Mobile o Claude
Code), qué ambiente (la URL del conector, tal cual
está guardada) y el mensaje literal que devolvió. Si
podés, agregá la respuesta de dynamo_session_status.