MCP

Probara expone un servidor Model Context Protocol (MCP) en:

https://app.probara.net/mcp

Cualquier cliente compatible con MCP (un asistente de IA o un IDE) puede conectarse a este endpoint para llamar a las herramientas de gestión de pruebas de Probara — proyectos, suites, casos de prueba, ejecuciones, defectos y más. Consulta la referencia de herramientas MCP para ver la lista completa y generada de todas las herramientas disponibles.

Autenticación

/mcp acepta cualquiera de los dos tipos de credencial como Bearer — consulta Autenticación API para la comparación completa:

• OAuth 2.1 (recomendado para clientes interactivos como Claude.ai, Claude Code, Cursor, ChatGPT) — el cliente descubre el servidor, se registra a sí mismo y una persona aprueba el acceso mediante una pantalla de consentimiento. No hay que copiar/pegar ningún secreto.
• Token API (recomendado para scripts e integraciones sin interfaz) — un token de larga duración probara_... creado en Menú del avatar → Tokens de API (/user/api-tokens), pegado directamente en el campo Bearer/Authorization del cliente.

Un token de aplicación (probara_app_..., desde Workspace → Integraciones) no es ninguno de los dos: solo envía resultados desde CI, y /mcp le responde 403 forbidden.

Una petición a /mcp sin credencial devuelve 401 con una cabecera WWW-Authenticate: Bearer resource_metadata="https://app.probara.net/.well-known/oauth-protected-resource" que apunta al descubrimiento del cliente.

Una credencial que el servidor no acepta (desconocida, revocada, caducada o emitida para otro recurso) también devuelve 401, con error="invalid_token" en esa cabecera. Entonces, un cliente OAuth renueva su token o vuelve a autorizarse.

Claude.ai (conector personalizado)

1. Abre Settings → Connectors → Add custom connector.
2. Introduce la URL del servidor: https://app.probara.net/mcp.
3. Claude.ai descubre automáticamente los metadatos de OAuth, se registra a sí mismo (Dynamic Client Registration) y te redirige a la pantalla de consentimiento de Probara.
4. Elige la organización a la que vincular la conexión y aprueba. Claude.ai ahora tiene una concesión OAuth limitada a esa organización.

Claude Code

1. Añade el servidor: claude mcp add --transport http probara https://app.probara.net/mcp.
2. Claude Code abre una ventana del navegador para el flujo de autorización/consentimiento de OAuth (mismo descubrimiento + DCR que Claude.ai).
3. Aprueba los scopes negociados y elige una organización. Si el cliente omite scope o envía un valor que Probara no reconoce, se aplica por defecto el conjunto completo soportado (mcp:read mcp:write); consulta Scopes para las reglas exactas de negociación.
4. Verifica la conexión: claude mcp list debería mostrar probara como conectado.

Cursor

1. Abre Settings → MCP → Add new MCP server.
2. Elige el transporte HTTP y define la URL como https://app.probara.net/mcp.
3. Cursor sigue el mismo flujo de descubrimiento OAuth/DCR/consentimiento; alternativamente, pega un token API en el campo de cabecera Bearer/Authorization del conector si tu versión de Cursor aún no soporta MCP OAuth.

ChatGPT

1. Abre Settings → Connectors → Add MCP server (Developer Mode / conectores personalizados).
2. Define la URL del servidor como https://app.probara.net/mcp.
3. Completa el flujo de consentimiento OAuth, o proporciona un token API como cabecera Bearer si tu plan de ChatGPT solo soporta conectores de cabecera estática.

Protocolo

El endpoint sirve dos revisiones del protocolo MCP. La revisión que negocia cada cliente determina la forma de sus respuestas. Todas las peticiones son POST: el servidor no mantiene un stream propio, así que GET y DELETE sobre /mcp responden 405.

• Las revisiones de 2025, como 2025-11-25, se atienden sin estado, y cada respuesta va en formato Server-Sent Events (text/event-stream).
• Los clientes de 2026-07-28 reciben un cuerpo JSON por petición y descubren el servidor con server/discover. Cada una de sus peticiones lleva las cabeceras MCP-Protocol-Version y Mcp-Method, y tools/call, prompts/get y resources/read llevan además Mcp-Name con el nombre de la herramienta, del prompt o la URI del recurso. Las cabeceras deben coincidir con el cuerpo: una petición con una cabecera ausente o que no coincide se rechaza con HTTP 400 y el error JSON-RPC -32020.

Las respuestas a tools/list, prompts/list, resources/list, resources/templates/list y server/discover de los clientes 2026-07-28 incluyen ttlMs: 300000 y cacheScope: "private". Un cliente puede reutilizar una de estas listas durante cinco minutos, y no debe compartirla entre usuarios. Las respuestas de 2025 no incluyen ninguno de los dos campos.

Llamar a una herramienta que no existe devuelve el error JSON-RPC -32602 (Tool <nombre> not found), no un resultado de herramienta. Una herramienta que existe y falla devuelve un resultado con isError: true.

El cuerpo de una petición está limitado a unos 43,7 MiB (45.787.820 bytes), lo justo para un adjunto de 32 MiB en base64 con el sobre JSON-RPC. Un cuerpo mayor se rechaza con 413.

/mcp responde solo para app.probara.net. Una petición dirigida a otro host, como una dirección *.workers.dev, se rechaza con 403. Un Origin del navegador debe nombrar el mismo host. Una petición sin Origin, como la de un cliente de servidor, no se ve afectada por esa comprobación.

Herramientas principales

Nueve herramientas cubren el trabajo habitual con pocas llamadas. Cada otra operación se usa con las cinco herramientas que también incluye una lista predeterminada, descritas en Operaciones y herramientas de ejecución más abajo.

Herramienta	Qué hace
get_project_context	Devuelve en una llamada las suites, los campos personalizados, las configuraciones, los hitos, los entornos y los miembros de un proyecto.
get	Lee cualquier entidad por su ID visible o su ULID. Con un ULID hay que indicar también kind.
query	Ejecuta una consulta PQL.
query_help	Lista los campos, operadores y valores PQL de cada entidad, con ejemplos que funcionan.
analyze_run	Agrupa los casos fallidos y bloqueados de una ejecución por defecto vinculado, y después por suite, con sus intentos.
upsert_test_cases	Crea o actualiza hasta 50 casos de prueba. Cada elemento indica un ID visible o una clave de automatización e informa de su propio resultado.
start_run	Inicia una ejecución desde una suite, un plan de pruebas, una consulta PQL o una lista de casos, con sus configuraciones y asignaciones.
record_results	Registra hasta 50 resultados en una ejecución por ID visible del caso de prueba, con resultados de pasos y adjuntos de evidencia.
file_defect	Registra un defecto a partir de un resultado y puede crear también su incidencia de GitHub o Jira.

upsert_test_cases asocia cada elemento a un caso de prueba por su ID visible o su clave de automatización. Un elemento con un ID visible que no existe falla, porque el servidor asigna los IDs visibles. Una clave de automatización que no coincide con ningún caso crea uno. Enviar el mismo lote otra vez no cambia nada e informa de cada elemento como unchanged. Si un elemento falla, los demás siguen.

Prompts y recursos

Un cliente también puede ofrecer prompts y recursos junto a las herramientas. Cada uno llega a los mismos datos que una herramienta, así que nada es accesible solo a través de ellos.

Tres prompts inician una tarea habitual. Cada uno responde con un mensaje que nombra las herramientas que hay que ejecutar, en orden:

Prompt	Argumentos	Herramientas que nombra
test_cases_from_issue	project_id y issue: una URL de incidencia de GitHub, owner/repo#n o una clave de incidencia de Jira	run_read_operation para leer la incidencia, después get_project_context y luego upsert_test_cases
triage_run	project_id y run: un ID visible como R-12, o un ULID	analyze_run, después get y luego file_defect
regression_for_pr	project_id, pull_request (una URL de pull request de GitHub o owner/repo#n) y changed_areas, que es opcional	query_help y query para encontrar los casos, después start_run

Probara no lee el diff de un pull request, así que changed_areas define el alcance de una ejecución de regresión.

Dos recursos contienen el mismo JSON que sus herramientas:

Recurso	URI	Misma respuesta que
Esquema PQL	probara://pql/schema	query_help
Contexto del proyecto	probara://projects/{project}/context, con el código del proyecto, como SHOP	get_project_context

Leer un recurso sigue el mismo camino que su herramienta: un proyecto desconocido responde con el mensaje de la herramienta como error JSON-RPC, con la URI en sus datos. Un recurso no tiene bloque para la nota de datos no confiables, así que la descripción de cada recurso indica que su JSON contiene datos de la organización.

Los recursos necesitan el alcance mcp:read. Cada prompt termina en una herramienta de escritura, así que los prompts necesitan mcp:read y mcp:write. Una concesión sin el alcance no lista ninguno, y una petición se rechaza con 403 y el desafío insufficient_scope, como ocurre con una herramienta oculta.

Operaciones y herramientas de ejecución

Una lista predeterminada incluye las nueve herramientas principales y otras cinco, así que un agente ve hasta 14 herramientas al conectarse, y menos con una concesión más acotada. El resto de las operaciones está en la referencia de herramientas, y cada una se usa en tres pasos:

1. search_operations busca operaciones por palabra clave, como proyecto o resultado de ejecución. Cada resultado da el nombre de la operación, un resumen de una línea y la herramienta de ejecución que la ejecuta.
2. describe_operation devuelve la descripción completa de la operación, el esquema JSON de sus entradas, sus anotaciones y su esquema de salida cuando lo declara.
3. run_read_operation, run_write_operation o run_delete_operation la ejecuta. Pasa el nombre de la operación como operation y sus entradas como arguments. El resultado es el de la propia operación.

Las tres herramientas de ejecución se reparten por riesgo. run_read_operation ejecuta operaciones de solo lectura, run_write_operation ejecuta escrituras que no eliminan nada y run_delete_operation ejecuta operaciones destructivas, como los borrados. Una herramienta de ejecución rechaza una operación de otro riesgo, y su error indica la herramienta que debe usarse. Un nombre desconocido responde con los nombres más parecidos.

Llamar una operación por su nombre directamente, como create_project, devuelve un error de herramienta que indica su herramienta de ejecución. Solo las nueve herramientas principales se llaman directamente.

Toda herramienta rechaza un argumento que no recibe: la llamada devuelve un error de herramienta que nombra ese argumento, y no se ejecuta nada. A través de una herramienta de ejecución, el error también lista los argumentos de la operación y marca los obligatorios. Lo mismo vale para una clave dentro de un elemento de record_results o upsert_test_cases, o dentro de una entrada de caseAssignees de start_run: un notes mal escrito rechaza toda la llamada en vez de registrar el resultado sin él.

Qué lista una concesión de solo lectura

Una concesión OAuth sin mcp:write lista las cinco herramientas principales de lectura y tres herramientas que buscan y leen operaciones: search_operations, describe_operation y run_read_operation. No lista ninguna herramienta de escritura, y la búsqueda devuelve solo operaciones de lectura. Una llamada de escritura desde esa concesión se rechaza con 403 y el desafío insufficient_scope que pide mcp:write, como antes. Una concesión OAuth que solo tiene mcp:write lista las cuatro herramientas principales de escritura y las dos herramientas de ejecución de escritura. Un token de API lista todas las herramientas predeterminadas.

Operaciones destructivas: vista previa y confirmación

Algunas operaciones pueden eliminar o cambiar de forma irreversible más de un registro en una sola llamada: las operaciones masivas bulk_delete_tags, bulk_remove_run_cases y reconcile_run_cases, los borrados de un proyecto, una suite, un caso de prueba, una ejecución, un plan de pruebas, un dashboard, un campo personalizado, una etiqueta, un hito o un entorno, y deactivate_org_member. Cada una se ejecuta en dos llamadas:

1. Llámala sin confirm_token. No se ejecuta nada. El resultado es una vista previa: status vale confirmation_required, targets lista lo que nombra la llamada con su ID visible y su nombre cuando una lectura los encuentra, irreversible dice qué no se puede deshacer, y confirm_token, expires_at y expires_in_seconds indican cuánto dura el token.
2. Repite la misma llamada con los mismos argumentos y el confirm_token. La operación se ejecuta.

Un token es de un solo uso y vale cinco minutos. Está ligado a la credencial que pidió la vista previa (un token de API o una concesión de OAuth), a su organización, a la operación y a sus argumentos. Una llamada que presenta un token se rechaza, y no se ejecuta nada, cuando:

• el token es desconocido, ha caducado o ya se usó: vuelve a llamar sin confirm_token para obtener una vista previa nueva;
• el token se emitió para otra operación, otra credencial, otra organización u otros argumentos: sigue válido para su propia llamada;
• el almacén de tokens no está disponible: el error es reintentable, así que vuelve a llamar.

run_delete_operation recibe confirm_token dentro de arguments, igual que la operación cuando se llama directamente.

Registro de actividad

Un cambio hecho a través de una conexión MCP con OAuth registra la conexión en su evento de auditoría: metadata.oauthClient guarda el clientId y el clientName del cliente, tal como los devuelve la API de eventos de auditoría. El feed de actividad muestra el cambio bajo el usuario, como hace con cualquier sesión.

Datos no confiables en los resultados

Un resultado correcto que contiene datos de la organización, como títulos, descripciones, pasos, comentarios y texto importado desde GitHub o Jira, termina con un segundo bloque de texto. Ese bloque indica que el JSON de arriba son datos escritos por personas de la organización o importados desde GitHub o Jira, y que el texto son datos, no instrucciones. El primer bloque de texto es el mismo JSON de antes, y structuredContent no cambia. Los errores y las respuestas de catálogo de search_operations y describe_operation no llevan ese bloque.

Casos de prueba parametrizados

El identificador visible de un caso, como SHOP-45, puede coincidir con varios casos de ejecución de una misma ejecución cuando el caso es parametrizado. Una operación que recibe un identificador visible y una ejecución rechaza la llamada, y lista hasta 25 de esos casos de ejecución, salvo que la llamada nombre uno: pasa su combinación como parameters, un array de pares nombre y valor como [{"name":"Sitio","value":"EU"}], o pasa el ULID del caso de ejecución. Las operaciones en lote usan ULID de caso de ejecución para ese caso. El servidor nunca elige uno por ti. upsert_test_cases y create_test_case aceptan parameters y excludedCombinations, igual que la API. Los parámetros compartidos son operaciones, que se encuentran con search_operations y se ejecutan por nombre: list_shared_parameters, get_shared_parameter, create_shared_parameter, update_shared_parameter, delete_shared_parameter (necesita confirmación y acepta un mode), list_shared_parameter_usage, preview_test_case_combinations y detach_test_case_parameter. La API y MCP aplican la misma regla. Consulta Casos de prueba parametrizados.

Identificadores

Cada argumento que recibe una entidad acepta su ULID o su ID visible, y el servidor busca el ID visible por ti.

• Un caso de prueba (SHOP-45) y una suite (SHOP-S3) llevan el código de su proyecto, así que no necesitan project_id.
• Una ejecución (R-12), un hito (M-5), un defecto (D-7), un plan de pruebas (PLAN-3), un paso compartido (SS-2) y una revisión (RV-4) se numeran dentro de cada proyecto. Envía project_id con ellos.
• Un caso de ejecución es un caso de prueba dentro de una ejecución. Las herramientas de caso de ejecución reciben el ID visible del caso de prueba junto con run_ulid. Las herramientas masivas de ejecución también reciben el ULID del caso de prueba.

Un ID visible que no existe responde con un error que lo nombra junto con el proyecto. Un código de proyecto que no existe responde con los códigos de proyecto válidos.

Anotaciones de las herramientas

Cada herramienta declara qué hace, para que un cliente que respeta esa declaración pueda pedir confirmación al usuario antes de una llamada arriesgada. Son indicaciones: el servidor nunca rechaza una llamada por ellas.

• Solo lectura: la herramienta solo lee datos.
• Destructiva: la herramienta elimina datos, o reemplaza en una sola llamada una lista, un documento o una credencial completa. Las herramientas de reemplazo y de conciliación reciben el conjunto completo que quieres, así que lo que omitas se elimina.
• Idempotente: repetir la misma llamada no tiene más efectos, así que reintentar una es seguro.
• Sistemas externos: la herramienta llega fuera de Probara: una escritura en GitHub o Jira, el lanzamiento de un flujo de trabajo de GitHub, una entrega a un webhook o un correo de invitación.

La referencia de herramientas MCP lista las indicaciones de cada herramienta. Al conectarse, el servidor también envía un resumen breve del modelo de datos y de los identificadores de Probara, que muchos clientes añaden al contexto del modelo.

Tamaño de las respuestas

Una herramienta de listado devuelve una página por llamada. La referencia de herramientas MCP indica el tamaño de página por defecto de cada herramienta y el argumento que lo cambia. La página más grande tiene 200 elementos.

Una página que aun así es demasiado grande para una respuesta (unos 10.000 tokens) se trata de una de estas dos formas:

• Los listados que continúan con nextCursor se recortan a los elementos que caben. El resultado incluye un objeto truncation: returned es el número de elementos que trae y pageItems el número que tiene la página. Su nextCursor apunta al último elemento que trae, así que la siguiente llamada devuelve el resto, sin huecos.
• Los listados que se recorren con page se rechazan con response_too_large y no se devuelve nada. El mensaje indica el pageSize que cabe; recorre el listado con ese tamaño.

get, list_results y list_run_cases también reciben fields, una lista con los nombres de los campos que se devuelven. query no lo recibe: la cláusula SELECT de la consulta indica sus columnas. El ID visible y el ULID se devuelven siempre. Un nombre desconocido se rechaza con fields_invalid, y el mensaje lista los nombres válidos.

Un registro único, o un listado sin argumento de paginación, se devuelve completo hasta unos 25.000 tokens. Si es mayor, se rechaza con response_too_large. El mensaje indica un filtro que añadir o una vista más reducida que pedir, o dice que la herramienta no tiene ninguna.

Solución de problemas

Síntoma	Causa probable
401 inmediato, sin ventana del navegador	El cliente no soporta el descubrimiento OAuth de MCP — usa un token API en su lugar
La pantalla de consentimiento muestra la organización equivocada	Elige otra organización en el selector de la pantalla de consentimiento antes de aprobar; cada concesión se vincula a exactamente una organización
Una llamada a herramienta devuelve 403 con insufficient_scope	La concesión OAuth no tiene el scope que la llamada necesita (mcp:read para leer, mcp:write para cambiar). Vuelve a autorizar para obtenerlo.
Una llamada a herramienta falla con forbidden y nombra el scope y tu rol	Tu rol en esa organización ya no permite el scope, aunque la concesión lo tenga. Volver a autorizar no cambia esto: un propietario o administrador de la organización debe cambiar tu rol. Consulta Autenticación.
503 con una cabecera Retry-After	Probara no pudo comprobar la credencial por un fallo temporal — espera los segundos de Retry-After y reintenta
429 con una cabecera Retry-After	Se alcanzó el límite de tasa por token o por organización — espera los segundos de Retry-After y reintenta
403 antes de ejecutar una herramienta	El cliente llama a /mcp en un host distinto de app.probara.net, o envía un Origin ajeno. Apúntalo a https://app.probara.net/mcp.
413 en una llamada a herramienta	El cuerpo de la petición supera el límite de 43,7 MiB. Los adjuntos admiten hasta 32 MiB; envía un archivo más pequeño.
JSON-RPC -32602, Tool … not found	El nombre de la herramienta no está en la lista que tiene el cliente. Vuelve a cargar la lista de herramientas; la lista guardada en caché dura hasta cinco minutos.
response_too_large en un resultado de herramienta	El resultado es demasiado grande para una respuesta. El mensaje indica el tamaño de página que hay que pedir, un filtro que añadir o una vista más reducida. Si no indica ninguno, la herramienta no tiene una forma menor de ese registro.