MCP: errors més clars, accés des de ChatGPT i llistes de tools més estables

Hem dedicat un temps a connectar el servidor MCP amb clients reals i hem corregit el que se’ls posava al camí. Tot el que segueix val per al servidor públic i per al servidor local stdio. Consulta la guia del protocol, connectar un client i el catàleg de tools.

Tornen els errors de negoci de les tools. Una tool que fallava per una raó de negoci arribava al client com un resultat amb el text genèric «An internal server error occurred.», que no donava a l’agent res amb què actuar. Ara una regla de negoci, un recurs inexistent, un conflicte o un error de validació retornen l’error JSON-RPC -32008: error.message és el codi v1, error.data.code és aquest mateix codi (per exemple task_not_found, invoice_not_found o task_label_name_in_use), error.data.http_status indica la categoria i un hint en castellà explica què fer. La manca de permís és -32005 insufficient_scope (403), una credencial invàlida és -32001 invalid_token (401) i un error inesperat és -32603 internal_error (500), sense exposar el missatge intern. Consulta errors.
private_key_jwt per a clients identificats per un document de metadades. Clients com ChatGPT o Claude, el client_id dels quals és una URL HTTPS, poden autenticar-se a /api/oauth/token, /revoke i /introspect amb un JWT signat amb RS256 o ES256, fent servir una clau publicada al jwks_uri del seu document. La metadata de /.well-known/oauth-authorization-server ho anuncia. Quan /oauth/authorize no pot acceptar un document, respon invalid_client amb un error_reason llegible i, en un navegador, mostra una pantalla que explica el problema en castellà, anglès i català. El registre dinàmic continua admetent només none i client_secret_basic. Els detalls són a clients identificats per un document de metadades.
Els cursors de tools/list duren 24 hores. Abans caducaven als 120 segons. Ara el cursor va lligat a la identitat que el va rebre (l’API key, o l’empresa, l’usuari i el client OAuth), de manera que renovar l’access token amb el refresh token no l’invalida. Si entre pàgines canvia el catàleg visible, el servidor retorna la primera pàgina del catàleg actual en lloc d’un error.
La primera pàgina inclou tot el catàleg. Sense per_page, una sola resposta conté totes les tools (la pàgina predeterminada n’hi ha prou per a tot el catàleg públic, unes 552 tools), així que un client que no pagini les veu totes i cap nextCursor.
Quatre noms antics de contactes es retiren el 15 de novembre de 2026. Fins aleshores search_clients, find_client_by_tax_id, create_client i bulk_create_clients continuen funcionant a tools/call i apunten a search_contacts, find_contact_by_tax_id, create_contact i bulk_create_contacts. No apareixen a tools/list i cada resposta inclou _meta["io.factuarea/deprecation"] amb la successora i la data. Passada aquesta data responen com a tools inexistents. Consulta la nota del catàleg.