L'auge dels agents d'intel·ligència artificial ha transformat la forma en què les aplicacions es comuniquen amb els serveis externs. Durant anys, les APIs REST han estat l'estàndard indiscutible per integrar sistemes, però el seu disseny, centrat en recursos i mètodes HTTP, respon a un consumidor molt diferent: un client programàtic que executa lògica fixa i predictible. Amb l'arribada del Model Context Protocol (MCP), el consumidor és ara un model de llenguatge que decideix en temps real quines operacions executar, com combinar-les i com interpretar els resultats. Aquest canvi de paradigma exigeix una revisió profunda de les bones pràctiques de disseny d'APIs. En Q2BSTUDIO, com a empresa especialitzada en aplicacions a mida, hem observat que adaptar interfícies pensades per a humans o clients rígids a entorns d'agents IA introdueix ineficiències i errors. Aquest article analitza nou principis clau que defineixen el nou disseny d'APIs per a MCP, i com les empreses poden aprofitar-los per construir solucions més robustes i eficients.
1. Dissenyar al voltant d'intencions, no a recursosEn REST, una operació típica s'alinea amb un recurs: crear un projecte, llistar les seves claus, enllaçar un repositori. El client orquestra aquestes trucades pas a pas. En MCP, l' agent ha de deduir la seqüència correcta a partir de la intenció de l' usuari, la qual cosa augmenta la probabilitat d' error i consumeix context valuós. La solució és dissenyar eines que encapsulin una intenció completa. Per exemple, en lloc d'exposar tres endpoints per configurar un projecte a Sentry, el seu servidor MCP ofereix una única eina create_project que realitza tota la seqüència de forma determinista. Aquest enfocament redueix la càrrega cognitiva de l' agent i millora la precisió. En el desenvolupament de ia per a empreses, aquesta abstracció és crucial perquè els agents puguin executar tasques complexes sense intervenció humana.
2. Operacions per lots per a eficiència de contextREST no defineix un estàndard per a operacions massives; cada trucada crea o modifica un sol element. Un agent que necessita generar múltiples pàgines, registres o configuracions repetirà la mateixa trucada una i altra vegada, duplicant arguments i augmentant la finestra de context. La solució és oferir eines que acceptin col·leccions completes. Notion, per exemple, va reemplaçar tres trucades al seu endpoint /pages per una sola eina notion-create-pages que rep un array de pàgines. Això no només estalvia tokens, sinó que centralitza la validació i el maneig d'errors en el servidor. Per a projectes de serveis cloud aws i azure, on els agents han d' aprovisionar múltiples recursos, el batch esdevé una pràctica indispensable.
3. Consolidar operacions estretament relacionadesEn REST, crear i actualitzar un mateix recurs solen ser dos endpoints diferents. A MCP, cada eina apareix en un menú pla; tenir dues eines molt similars competeix per l' atenció del model i duplica la documentació. Un agent pot no saber si ha de crear o actualitzar un issue, i una eina unificada (issue_write) amb un paràmetre method resol l'ambigüitat. GitHub aplica aquest patró en el seu servidor MCP, agrupant 13 camps comuns sota un mateix nom. Aquesta consolidació és un exemple de com el programari a mida s' ha d' adaptar a les necessitats del consumidor, en aquest cas un agent d' IA.
4. Fer explícita la semànticaREST utilitza codis d'estat HTTP (401, 404) i capçaleres per comunicar resultats. Un client programàtic sap com interpretar-los. Un agent, en canvi, només veu el resultat d'una trucada. Un error com "Unauthorized" deixa massa preguntes obertes: què va fallar? va canviar l'estat? què ha de fer l'usuari? L' eina ha de retornar una estructura rica en informació, incloent-hi el motiu de l' error, si hi va haver canvis d' estat, i una ruta de recuperació. Per exemple, una actualització de comanda que falla per autenticació caducada hauria d'indicar: "La direcció no es va actualitzar perquè la sessió ha expirat. Demana a l'usuari que reconnecti el compte." Aquest nivell de detall redueix les interpretacions errònies del model. En Q2BSTUDIO integrem aquests patrons en les nostres solucions de ciberseguretat i automatització per garantir que els agents prenguin decisions informades.
5. La documentació com a codi de controlEn REST, la documentació es consulta durant el desenvolupament; un cop compilat el client, els canvis en la documentació no afecten el comportament. A MCP, l'agent llegeix la descripció de l'eina en temps d'execució; cada paraula influeix en la selecció i en la construcció d' arguments. Una descripció vaga com "Buscar logs" deixa massa marge a la interpretació. Una descripció precisa especifica quins logs busca, com identificar el servei, el rang temporal permès i què exclou (per exemple, esdeveniments d'auditoria). Això converteix la documentació en un artefacte crític de control de flux. Els equips de desenvolupament han de tractar els canvis en les descripcions com canvis de codi, sotmetent-los a proves. En l'àmbit de la intel·ligència de negoci, on els agents han de consultar fonts de dades heterogènies, una documentació ben dissenyada evita trucades invàlides i optimitza el rendiment.
6. Suggerir accions següentsHATEOAS, un principi de REST que rara vegada s'implementa, cobra nova vida a MCP. Consisteix que la resposta d' una eina inclogui enllaços o suggeriments sobre quina acció realitzar a continuació. Un agent no té un pla predefinit; si el resultat d'una traça de Sentry indica que hi ha una conversa d'IA associada, el servidor pot retornar un suggeriment estructurat per cridar get_ai_conversation_details amb els identificadors ja emplenats. Això redueix la necessitat que l'agent busqui a la superfície d'eines o infereixi la transició. Les empreses que desenvolupen agents IA poden beneficiar-se enormement d' aquest patró per crear experiències fluides i autònomes.
7. Filtrat de camps per estalviar contextREST sovint retorna representacions completes de recursos, deixant que el client extregui els camps que necessita. A MCP, cada camp retornat entra en el context del model, i si no és rellevant, desperta tokens i pot confondre l'agent. Oferir un paràmetre de filtratge de camps (similar a les projeccions de GraphQL) permet a l'agent sol·licitar només les dades necessàries per a la decisió immediata. Per exemple, una eina inspect_customer que accepti fidelds retorna únicament l'identificador, nom i estat de risc; la resta queda fora del context. Aquest principi és especialment útil en aplicacions de programari a mida on es manegen grans volums de dades.
8. Protegir operacions destructivesREST assumeix que el client ja ha validat l'operació a través de la seva interfície d'usuari. A MCP, el model decideix en calent; una descripció d'eina pot instruir l'agent perquè demani confirmació explícita a l'usuari abans d'eliminar un arxiu. A més, la resposta ha de confirmar el canvi, indicar si hi va haver modificació d'estat i oferir una ruta de recuperació (com una còpia de seguretat temporal). Per exemple, remove_file retorna la ruta de backup i la seva data d'expiració. Aquest nivell de protecció és crític en entorns de producció on la ciberseguretat i la integritat de les dades són prioritàries.
9. Divulgar eines de forma progressivaUna API REST pot exposar cents d'endpoints perquè cada aplicació selecciona els que necessita durant el desenvolupament. Un agent no pot fer aquesta selecció permanent; necessita conèixer només les eines rellevants per al context actual. Carregar totes les definicions a l' inici consumeix context i augmenta la confusió. La divulgació progressiva consisteix a exposar primer eines de recerca o meta-eines que, a partir de la consulta de l' usuari, carreguin els detalls específics. Stripe utilitza aquest patró: primer un stripe_api_search que identifica el mètode, després stripe_api_details per als seus paràmetres, i finalment stripe_api_read/write per executar-lo. Per a superfícies petites (menys de cinc eines), no és necessari; però quan es manegen desenes o cents d'operacions, és imprescindible. En Q2BSTUDIO apliquem aquesta filosofia en el disseny de sistemes d' automatització que integren múltiples fonts de dades i serveis.
Conclusió: un nou contracte de dissenyEl pas de REST a MCP no és una simple migració tècnica; és un canvi profund en la forma de pensar les interfícies. El backend pot ser el mateix, però el consumidor —un agent d'intel·ligència artificial— opera amb lògica dinàmica, context limitat i sense la possibilitat de llegir documentació estàtica. Cada principi aquí descrit busca traslladar al servidor la intel·ligència que abans residia en el codi del client: agrupar intencions, fer explícita la semàntica i protegir l'usuari. Les empreses que adoptin aquest nou paradigma no només milloraran l'eficiència dels seus agents, sinó que reduiran costos de context i errors. En Q2BSTUDIO, com a experts en ia per a empreses i serveis d'intel·ligència de negoci, ajudem les organitzacions a redissenyar els seus APIs i processos perquè els agents IA puguin operar de forma autònoma i segura. El futur de la integració és conversacional, i el disseny ha d'evolucionar amb ell.
