MCP

La misma API, dirigida a un asistente en vez de a un escenario. Un cliente MCP decide qué llamar mientras se ejecuta, a partir de las descripciones de las herramientas, así que alcanza exactamente lo que alcanzan sus credenciales, y bajo cada herramienta hay una llamada a la API pública.

Un solo endpoint

Todo va a POST /v1/mcp. No hay sesión que abrir ni flujo que mantener: GET y DELETE responden 405, y cada mensaje es su propia petición.

POST https://api.mosaqo.app/v1/mcp
Authorization: Bearer $MOSAQO_KEY
MCP-Protocol-Version: 2026-07-28

Se atienden todas las revisiones del protocolo de 2025-03-26 a 2026-07-28. Un cliente que empieza con initialize recibe el saludo que espera; el que declara su versión en cada petición se atiende así.

Conectar con una clave de API

La vía más rápida, y la correcta para una herramienta que ejecutas tú. Cualquier clave sirve como token bearer, y las herramientas ofrecidas se recortan a los permisos de esa clave.

La mayoría de los clientes acepta un bloque como este:

{
  "mcpServers": {
    "mosaqo": {
      "type": "http",
      "url": "https://api.mosaqo.app/v1/mcp",
      "headers": { "Authorization": "Bearer $MOSAQO_KEY" }
    }
  }
}

curl -X POST https://api.mosaqo.app/v1/mcp \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

Conectar mediante OAuth

Para un conector en el directorio de otro, donde la persona nunca toca una clave. El descubrimiento sigue RFC 9728 y RFC 8414, los clientes se registran solos con RFC 7591, y cada autorización usa PKCE con S256.

curl https://api.mosaqo.app/.well-known/oauth-protected-resource
curl https://api.mosaqo.app/.well-known/oauth-authorization-server

Una llamada no autorizada dice por sí misma adónde ir y qué pedir:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Mosaqo MCP",
  resource_metadata="https://api.mosaqo.app/.well-known/oauth-protected-resource",
  scope="qr:read analytics:read reviews:read exports:read"

Quien aprueba ha iniciado sesión en Mosaqo, elige el espacio al que aplica y solo puede hacerlo donde es propietario o administrador — la misma línea que decide quién puede emitir una clave de API. Después puede desconectarlo en Bulk & API.

Qué puede hacer un asistente

Los permisos que ya conoces, sin cambios. Una herramienta que las credenciales no permiten no aparece en tools/list ni se llama nombrándola, así que la respuesta viva para cualquier conexión es tools/list.

Scope	Permite
`qr:read`	Listar y leer códigos QR, carpetas y plantillas
`qr:write`	Crear, modificar, redirigir, publicar, archivar y eliminar
`exports:read`	Descargar tarjetas renderizadas
`analytics:read`	Analíticas agregadas y escaneos individuales
`bulk:write`	Crear y leer trabajos por lotes
`webhooks:write`	Administrar suscripciones de webhooks
`reviews:read`	Lugares, encuestas y cómo van — nunca las respuestas en sí

Qué no alcanzará nunca

Lo que la gente escribió en una encuesta. reviews:read abre tus lugares, tus encuestas y cómo van: los recuentos, las puntuaciones, el reparto de respuestas por pregunta. Las frases que escribió un visitante no se devuelven aquí más que en ningún otro sitio al que lleguen unas credenciales, por la misma razón por la que los eventos feedback.* llevan una puntuación y nunca las palabras.

Borrar un código. La ruta REST pide una confirmación escrita porque destruir la redirección de un código impreso no se deshace, y esa no es una confirmación que un asistente dé en nombre de alguien. En su lugar se ofrece archivar, y eso sí se revierte.

Escribir está marcado como escribir. Una herramienta que cambia algo lleva readOnlyHint: false, y archivar lleva destructiveHint: true: eso es lo que hace que un cliente se detenga y pregunte a una persona antes de ejecutar.