Construir un MCP con Autodesk APS: del endpoint a una herramienta útil
La primera herramienta MCP que construiría sobre Autodesk APS tendría una tarea pequeña: listar los hubs accesibles con una conexión. El endpoint ya existe, pero todavía hay que decidir cómo recibe el servidor la credencial, qué devuelve al cliente y qué hace si Autodesk falla. Voy a usar ese caso para convertir una consulta HTTP en una herramienta que podamos probar por separado.
El artículo de Autodesk del 8 de abril de 2026 propone empezar con capacidades pequeñas. Aquí vamos a recorrer una lectura de hubs, los espacios desde los que después se pueden consultar proyectos. El ejemplo permite entender el contrato y probarlo con respuestas simuladas; no añade nuevas funciones a Issues Manager ni se presenta como una conexión ya validada con una cuenta Autodesk real.
Tabla de contenidos
Qué merece convertirse en una herramienta
Una API organiza operaciones para aplicaciones que conocen su funcionamiento. Un asistente necesita además decidir cuándo le sirve cada operación, qué datos debe aportar y cómo interpretar el resultado. Por eso, copiar todos los endpoints de APS en un catálogo MCP no resuelve por sí solo la integración. Puedes acabar con muchas herramientas difíciles de distinguir y con la misma pregunta pendiente: cuál debería utilizarse para responder a esta persona, en este momento.
Una herramienta MCP ofrece una capacidad invocable mediante un nombre, una descripción y un esquema de argumentos. En nuestro caso, list-hubs describe una lectura concreta: obtener una página de los hubs accesibles con la conexión Autodesk que corresponda. No necesita pedir al usuario un identificador que todavía desconoce. Tampoco promete enumerar sus proyectos, revisar incidencias o corregir modelos. Ese límite permite explicar su utilidad antes de escribir código y comprobar después si la implementación hace exactamente eso.
Los recursos y los prompts tienen otras funciones. Un recurso permite acceder a contenido identificado por una URI; un prompt puede ofrecer una plantilla de interacción. Conviene escogerlos por el problema que resuelven, en lugar de repartir las operaciones entre categorías para completar el catálogo. Una consulta de hubs encaja como herramienta porque se ejecuta para obtener un resultado actual. Un documento de criterios de revisión podría servirse como recurso. Son necesidades distintas, aunque las dos ayuden al mismo asistente.
La referencia de APS para listar hubs sitúa la operación en GET /project/v1/hubs, con el scope data:read. Ese permiso debe formar parte de una conexión preparada para consultar esos datos. Un inicio de sesión que solo permite leer el perfil no se convierte en acceso a proyectos por añadir una herramienta MCP delante. La autorización de Autodesk sigue siendo necesaria y los permisos de cada recurso siguen contando.
Reutilizaría la conexión y los controles del backend antes de añadir otra gestión de tokens al MCP. La versión del login de Issues Manager permite estudiar esa base. El ejemplo de este artículo se concentra en el contrato de una herramienta de lectura y utiliza respuestas simuladas.
Dónde vive la conexión y quién puede utilizarla
El transporte decide cómo se comunican el cliente y el servidor MCP. Con STDIO, un cliente puede iniciar un proceso local e intercambiar mensajes con él. Streamable HTTP permite atender peticiones a través de la red, con las decisiones de despliegue y autorización que eso implica. Issues Manager ya utiliza HTTP como base; introducir un paso local con STDIO solo para acortar una demostración no resolvería las necesidades del servicio que se pretende construir.
Esta elección suele mezclarse con otra: dónde guardar la conexión Autodesk. Son cuestiones relacionadas, pero diferentes. Un servicio HTTP puede resolver la identidad en cada petición y recuperar la conexión desde un almacén externo, sin conservar una sesión MCP persistente en la memoria del proceso. Eso permite atender otra petición en una instancia distinta siempre que ambas apliquen las mismas reglas y accedan de forma segura al estado necesario.
Piensa en dos personas que utilizan el mismo asistente. La herramienta puede llamarse igual para ambas, pero el proveedor de credenciales debe recuperar la conexión autorizada de quien está haciendo la petición. Un token global compartido devolvería datos según la cuenta propietaria de ese token, aunque la conversación perteneciese a otra persona. El esquema de argumentos no debería ofrecer una casilla para que el modelo elija libremente la identidad ni para que introduzca un bearer token.
En un servicio remoto también hay que distinguir la autorización para entrar al servidor MCP del permiso para consultar APS. La primera controla quién puede invocar nuestras herramientas; la segunda determina qué puede hacer la conexión Autodesk utilizada. Resolver una frontera no elimina la otra. El artículo sobre autenticación MCP y APS desarrolla esa separación y por qué los tokens emitidos para un servicio no deben reutilizarse indiscriminadamente como credenciales de otro.
Para estas decisiones conviene separar el transporte MCP de la autorización del cliente. El transporte organiza los mensajes; la autorización determina quién puede utilizar el recurso. Después queda obtener la conexión APS que corresponda a esa identidad.
Una lectura pequeña que explica sus límites
La función siguiente registra la herramienta en un servidor creado previamente. Recibe por separado un proveedor de access token y una función para hacer peticiones HTTP. Esa separación permite probar la respuesta sin consultar Autodesk y, al componer un servicio real, obliga a decidir cómo se obtiene la credencial. Aquí no se abre un puerto, no se implementa OAuth y no se guarda una sesión: se delimita la lectura que esas otras piezas podrán utilizar.
/** Ejemplo editorial aislado. El proveedor se resuelve fuera de los argumentos del modelo. */
export function registerHubsTool(server, getAccessToken, request = fetch) {
server.registerTool(
"list-hubs",
{
description: "Lee una página de hubs accesibles en Autodesk APS.",
inputSchema: {},
annotations: { readOnlyHint: true },
},
async () => {
const token = await getAccessToken();
const response = await request(
"https://developer.api.autodesk.com/project/v1/hubs",
{
headers: { Authorization: `Bearer ${token}` },
signal: AbortSignal.timeout(10000),
redirect: "error",
},
);
if (!response.ok) throw new Error(`APS HTTP ${response.status}`);
const body = await response.json();
if (!Array.isArray(body.data)) throw new Error("Respuesta APS no válida");
const hubs = body.data.map((hub) => {
if (
typeof hub?.id !== "string" ||
typeof hub?.attributes?.name !== "string"
) {
throw new Error("Hub APS no válido");
}
return { id: hub.id, name: hub.attributes.name };
});
const output = { hubs, hasMore: Boolean(body.links?.next) };
return {
content: [{ type: "text", text: JSON.stringify(output) }],
structuredContent: output,
};
},
);
}
La URL es fija y las redirecciones se rechazan. El modelo no puede convertir esta herramienta en una petición a una dirección arbitraria. El tiempo máximo de diez segundos evita dejar la consulta esperando indefinidamente, aunque un servicio completo todavía tendría que definir cómo comunica una interrupción y cuándo permite repetir la operación. El token se utiliza para la cabecera de autorización y no se incluye en la salida.
Antes de devolver datos se comprueba que exista una colección y que cada hub tenga identificador y nombre. Es una validación mínima, suficiente para el contrato mostrado. Si cambia la forma de la respuesta, el ejemplo falla en lugar de fabricar una lista aparentemente correcta. Además, devuelve solo los campos que se quieren utilizar. Enviar al contexto del asistente toda la respuesta de la API aumentaría el ruido y la información expuesta sin aportar necesariamente una mejor respuesta al usuario.
La salida combina structuredContent, que conserva los datos procesables, con su representación JSON en content, útil para clientes que consuman la parte textual. La anotación readOnlyHint describe la intención de la herramienta; no impide por sí misma que un callback mal implementado haga una escritura. El servidor debe garantizar el comportamiento que anuncia. Una etiqueta de solo lectura ayuda a interpretar una capacidad, pero no sustituye las restricciones de su implementación.
También hay un límite visible: hasMore indica que APS ha anunciado otra página. El código no la sigue. Si la respuesta contiene varios hubs y ese indicador es verdadero, el asistente debería explicar que está mostrando una parte del resultado. Para responder «estos son todos tus espacios» haría falta completar la paginación con límites y comprobaciones. Es una diferencia pequeña en el JSON y bastante importante en lo que el usuario puede concluir.
Qué demuestran las pruebas antes de conectar una cuenta
El ejemplo dispone de cuatro pruebas automatizadas con cliente y servidor del SDK unidos mediante un transporte en memoria. Las respuestas HTTP están simuladas. Este montaje comprueba que la herramienta se descubre y se invoca a través del SDK, y permite reproducir condiciones que no conviene provocar al azar en una cuenta real. No demuestra que un usuario tenga acceso a un hub ni que el despliegue HTTP esté correctamente autorizado.
La primera prueba verifica la URL fija, la cabecera construida con una credencial sintética y la salida normalizada sin devolver el token. Otra comprueba que el enlace de siguiente página active hasMore. Las dos restantes cubren una respuesta 401 y una estructura inesperada. En ambos casos debe aparecer un error, en lugar de una lista vacía que el asistente pueda interpretar como ausencia de hubs. Conservar la diferencia entre «no hay resultados» y «no se ha podido consultar» evita conclusiones equivocadas desde el primer ejemplo.
Una vez que pase este contrato, la siguiente comprobación será sustituir la respuesta simulada por una conexión APS real y probar permisos retirados, caducidad y paginación. Separar ambas pruebas permite localizar si un fallo está en la herramienta o en el acceso a Autodesk.
TypeScript tiene sentido en este ejemplo porque permite aprovechar el SDK y las pruebas ya preparadas. Un equipo con servicios Python o .NET puede tener buenas razones para utilizar sus respectivos SDK y conservar su lógica de negocio. Las capas de conveniencia y sus versiones requieren una evaluación propia; compartir la palabra MCP no hace intercambiables las APIs de esas bibliotecas. El coste de mantener la integración suele pesar más que ahorrar unas líneas en la primera demostración.
He empezado por una lectura pequeña para poder comprobar qué entra, qué sale y qué error recibe el cliente. Ampliaría el catálogo cuando ese recorrido esté claro: cada herramienta nueva debería resolver una tarea reconocible y conservar los mismos controles de identidad.
Puedes descargar el ejemplo completo con sus cuatro pruebas. Descomprímelo en una carpeta nueva, instala las dependencias con npm install y ejecuta npm test (Node.js 22 o posterior). El ZIP incluye la herramienta, las pruebas, las versiones de dependencias y un README. Utiliza un transporte MCP en memoria y respuestas APS simuladas: no necesita credenciales ni consulta una cuenta Autodesk.
Respuestas