MCP: errores más claros, acceso desde ChatGPT y listas de tools más estables

Hemos dedicado un tiempo a conectar el servidor MCP con clientes reales y hemos corregido lo que se interponía en su camino. Todo lo que sigue vale para el servidor público y para el servidor local stdio. Consulta la guía del protocolo, conectar un cliente y el catálogo de tools.

Vuelven los errores de negocio de las tools. Una tool que fallaba por una razón de negocio llegaba al cliente como un resultado con el texto genérico «An internal server error occurred.», que no le daba al agente nada con lo que actuar. Ahora una regla de negocio, un recurso inexistente, un conflicto o un fallo de validación devuelven el error JSON-RPC -32008: error.message es el código v1, error.data.code es ese mismo código (por ejemplo task_not_found, invoice_not_found o task_label_name_in_use), error.data.http_status indica la categoría y un hint en español explica qué hacer. La falta de permiso es -32005 insufficient_scope (403), una credencial inválida es -32001 invalid_token (401) y un fallo inesperado es -32603 internal_error (500), sin exponer el mensaje interno. Consulta errores.
private_key_jwt para clientes identificados por un documento de metadatos. Clientes como ChatGPT o Claude, cuyo client_id es una URL HTTPS, pueden autenticarse en /api/oauth/token, /revoke e /introspect con un JWT firmado con RS256 o ES256, usando una clave publicada en el jwks_uri de su documento. El metadata de /.well-known/oauth-authorization-server lo anuncia. Cuando /oauth/authorize no puede aceptar un documento, responde invalid_client con un error_reason legible y, en un navegador, muestra una pantalla que explica el problema en español, inglés y catalán. El registro dinámico sigue admitiendo solo none y client_secret_basic. Los detalles están en clientes identificados por un documento de metadatos.
Los cursores de tools/list duran 24 horas. Antes caducaban a los 120 segundos. Ahora el cursor va ligado a la identidad que lo recibió (la API key, o la empresa, el usuario y el cliente OAuth), de modo que renovar el access token con el refresh token no lo invalida. Si entre páginas cambia el catálogo visible, el servidor devuelve la primera página del catálogo actual en lugar de un error.
La primera página incluye todo el catálogo. Sin per_page, una sola respuesta contiene todas las tools (la página predeterminada basta para todo el catálogo público, unas 552 tools), así que un cliente que no pagine las ve todas y ningún nextCursor.
Cuatro nombres antiguos de contactos se retiran el 15 de noviembre de 2026. Hasta entonces search_clients, find_client_by_tax_id, create_client y bulk_create_clients siguen funcionando en tools/call y apuntan a search_contacts, find_contact_by_tax_id, create_contact y bulk_create_contacts. No aparecen en tools/list y cada respuesta incluye _meta["io.factuarea/deprecation"] con la sucesora y la fecha. Pasada esa fecha responden como tools inexistentes. Consulta la nota del catálogo.