Servidor MCP

El servidor Power Portals Pro MCP proporciona a los asistentes de programación de IA conocimiento directo de este framework mientras construyes. Es un servidor Model Context Protocol , viene con el framework y no hay clave de licencia ni nada a lo que suscribirse.

Por qué existe

Dos cosas que un agente no puede obtener solo con la documentación, y ambas causan código roto:

Lo que responde

Nota

Todas las herramientas de Dataverse leen metadatos. Ninguna lee, escribe o borra un registro, así que apuntar a un agente a un entorno de producción le permite aprender la forma de tus datos sin poder tocarlos.

Añadirlo a un proyecto

Dos lugares donde puede vivir

Aquí hay un huevo y la gallina que merece la pena ser explícito. Las plantillas escriben la configuración en el proyecto que crean, pero el servidor es más útil antes de que ese proyecto exista, cuando eliges una plantilla y sus opciones. Así que instálala una vez para ti y deja que el archivo por proyecto tome el control a partir de ahí.

Una vez por máquina, para cualquier carpeta

Esto hace que el servidor esté disponible en todas partes, incluyendo una carpeta vacía en la que vas a andamiar. Luego puede responder qué plantilla usar, qué significan las opciones y qué configurar después. Deliberadamente desfijado, para que registre la última versión:

Visual Studio lee un nivel .mcp.json de usuario desde tu carpeta de perfil, Cursor usa ~/.cursor/mcp.json, y VS Code tiene una configuración MCP a nivel de usuario en sus configuraciones. Cada uno ocupa el mismo servers bloque.

Por proyecto, fijado a su versión

Los proyectos creados a partir de las plantillas Power Portals Pro ya están conectados por cable: la plantilla escribe a .mcp.json en la raíz de la solución, fijada a la versión correspondiente del servidor. No hay nada que hacer.

Para añadirlo a un proyecto existente, ejecuta esto en la carpeta del proyecto — escribe lo .mcp.json mismo para ti:

Fíjate en lo que eso no hace: deja el servidor sin fijar, así que la carpeta recibe el servidor publicado más reciente en lugar del que coincide con los PowerPortalsPro.* paquetes que referencias tu proyecto. Ese es el valor por defecto correcto para un proyecto que sigue la versión actual, y el incorrecto para un proyecto que se mantiene deliberadamente en una versión antigua — fijalo añadiendo la versión, como hacen las plantillas:

O escribe el archivo tú mismo, en la raíz de tu solución:

¿Qué archivo lee tu editor?

Visual Studio 2022 17.14+ y Visual Studio 2026 leen .mcp.json desde la carpeta de la solución, y Claude Code también. VS Code lee .vscode/mcp.json y Cursor .cursor/mcp.json lee — ambos usan el mismo servers bloque, así que cópialo a otro.

dnx viene con el SDK .NET 10, que ya tienes: todos los proyectos Power Portals Pro están alojados por ASP.NET Core, incluyendo React SPAs. La primera partida descarga el paquete y lo almacena en caché.

Tener ambos es la configuración prevista. Las dos entradas usan el mismo nombre de servidor, así que un cliente que entiende ambos ámbitos usa el del proyecto — lo que significa que obtienes las respuestas con versiones dentro de un proyecto y las más recientes en cualquier otro lugar.

El comando ppp-mcp, si lo quieres

Los comandos de terminal en esta página — login, status, logout y el resto — se ejecutan dnx sin nada instalado: dnx PowerPortalsPro.Mcp login. Si prefieres escribir ppp-mcp login, instala el paquete como una herramienta global .NET:

Eso pone ppp-mcp en tu PATH: el SDK .NET normalmente añade su carpeta global de herramientas — %USERPROFILE%\.dotnet\tools en Windows, ~/.dotnet/tools macOS y Linux — a él. Si no se encuentra el comando, abre un nuevo terminal; si aún no se encuentra, añade esa carpeta a PATH ti mismo.

Una herramienta global permanece en la versión que instalaste, donde dnx recoge la más reciente, así que actualízala como se describe a continuación. Tu cliente MCP puede seguir lanzando el servidor de dnx cualquier forma: ambos leen las mismas asignaciones de carpetas y los mismos inicios de sesión guardados.

Comprobar que funciona

Pregunta a tu asistente algo que solo el servidor pueda responder — por ejemplo: "usa get_component_api para mostrarme todos los parámetros en MainGrid". Si la herramienta no está disponible, el cliente no ha detectado el archivo de configuración; la mayoría necesita reiniciar después de añadirlo.

Actualización

Cómo actualices depende de cómo lo hayas instalado.

Instalado como una herramienta global (dotnet tool install --global PowerPortalsPro.Mcp, que pone ppp-mcp en tu PATH):

Importante

Cierra primero tu cliente MCP. Un servidor en funcionamiento mantiene abiertos sus propios archivos, y la actualización falla con Access to the path ... denegado hasta que nada los usa. Inicia el cliente de nuevo después para cargar la nueva versión.

Conexión a Dataverse

Las herramientas de documentación no necesitan ninguna configuración. Las herramientas de metadatos necesitan una conexión con tu entorno, y esa conexión pertenece a la carpeta, no a la máquina. Ejecuta esto una vez en el proyecto:

Los entornos pertenecen a la carpeta

Eso vincula esta carpeta a un entorno. Si trabajas con varios clientes, cada proyecto permanece conectado en sus propios entornos y los agentes en diferentes carpetas nunca se cruzan. Esto es lo único que pac auth select no se puede hacer: cambia un único perfil de toda la máquina, así que cambiar de cliente en un solo lugar lo cambia en todas partes.

El inicio de sesión utiliza por defecto el flujo de código del dispositivo, así que funciona por SSH, dentro de un contenedor y en WSL, y puedes terminarlo en un teléfono. Paso --browser si prefieres abrir uno.

Varios entornos en una sola carpeta

Una carpeta puede iniciar sesión en varios entornos a la vez — por ejemplo, los entornos de desarrollo, pruebas y producción de un cliente. Cada login uno con otro entorno la añade a la lista de la carpeta y --name le da el nombre con el que te referirás:

El primer entorno es el principal, y cada herramienta actúa en consecuencia a menos que pidas otra: "listar las opiniones sobre contacto en la prueba" se responde desde test, y la siguiente pregunta vuelve a la primaria. Pasa --make-primary a login para añadir un entorno como principal en su lugar, o pide a tu asistente que las reordene.

Cada respuesta que ha llegado a Dataverse empieza nombrando el entorno del que proviene — su nombre, su posición y su URL — por lo que un cambio realizado en producción nunca se lee igual que uno hecho en desarrollo.

Dónde se almacenan las cosas

La caché de tokens está codificada por entorno, así que un segundo clon del repositorio del mismo cliente no te pide que vuelvas a iniciar sesión, mientras que un cliente diferente siempre lo hace — y también lo hace cada entorno que añades a una carpeta.

Mandos

Ejecutalos como dnx PowerPortalsPro.Mcp <command>, o como ppp-mcp <command> si hubieras instalado la herramienta global. Todos estos actúan sobre la carpeta actual a menos que pases --workspace.

Otras formas de conectar

El entorno y las credenciales se resuelven en este orden, por lo que la declaración de intenciones más explícita gana:

  1. Variables de entorno — PPP_D365_URL, PPP_D365_CLIENT_ID y PPP_D365_CLIENT_SECRET en el bloque del env servidor. Un principal de servicio, y la forma de conectarlo en CI o en un contenedor compartido. PPP_D365_URL se convierte en el entorno primario, antes de cualquiera al que la carpeta está vinculada, y el principal de servicio se usa solo para el principal.
  2. El inicio de sesión de la carpeta — escrito por login. La ruta normal.
  3. Los propios ajustes del proyecto — los mismos D365:Url, D365:ClientId y D365:ClientSecret (o D365:Secret) el propio portal lee de secretos de usuario y appsettings. Por tanto, un proyecto Power Portals Pro configurado a menudo no necesita iniciar sesión en absoluto.

Perfiles CLI de Power Platform

Si ya tienes entornos en pac, puedes empezar desde uno en lugar de buscar una URL:

La CLI no tiene ningún comando que entregue un token de acceso, y mantiene las credenciales en su propio almacén, por lo que su sesión no puede reutilizarse directamente. Lo que --pac-profile sí hace es tomar el entorno y la cuenta de un perfil y iniciar sesión como esa cuenta — normalmente sin que se lo pidan, porque ya tienes una sesión.

Nota

El perfil activo de la CLI nunca cambia. pac auth select No se utiliza deliberadamente: movería todos los proyectos a la vez.

Las herramientas

Rara vez necesitas nombrar una herramienta — los asistentes la eligen de las descripciones — pero ayuda saber qué hay ahí.

Documentación, siempre disponible

Tu entorno, una vez conectado

Elegir entre entornos

Cada herramienta que llega a Dataverse toma un nombre opcional environment — un nombre como test, una posición como 2, o la URL — y usa el principal sin uno. Un nombre que no coincide con nada es rechazado junto con la lista de entornos que existen, nunca se asocia con el más cercano.

Añadir un entorno requiere iniciar sesión, así que solo login lo hace. El resto puede hacerlo tu asistente cuando lo pidas. Mover un entorno a la posición 1 cambia donde cada escritura posterior se hace por defecto, así que set_environment_index primero te pregunta cuándo cambiaría el primario, y remove_environment siempre pregunta.

Los propios registros

Los metadatos indican cuál es la forma; estos indican qué contiene realmente — qué valor de conjunto de opciones tiene realmente una fila, si una consulta está poblada, si la fila que acaba de escribir tu código salió bien. Un agente que no puede mirar adivinará en su lugar.

Leer se lee como tú — el principal del servicio o el usuario iniciado sesión, nunca un usuario del portal. Ninguno de los permisos de tabla, columnas o filtros de fila del portal se aplica, así que esto muestra lo que hay en el entorno y no lo que se mostraría a un usuario dado del portal. El FetchXML de una vista guardada se ejecuta literalmente.

Poner en marcha un nuevo proyecto

get_upgrade_plan es la que llama antes de cambiar una cadena de versión. Lee la versión que hace referencia este proyecto, calcula qué versiones se encuentran entre esa y el destino, y devuelve cada cambio disruptivo en ellas con sus instrucciones de migración — junto con los archivos que nombran una versión, incluyendo el pin .mcp.json del servidor que nada más detectaría. Al remover los paquetes sin ella, se producen errores de compilación cuya causa es varias versiones atrás.

La solución gestionada

El framework debe PowerPortalsProCore instalarse antes de que se ejecute un portal, y PowerPortalsProLocalization si lo localizas. Estos obtienen una versión y la importan sin la CLI de Power Platform, así que el entorno al que llegan es al que está vinculada esta carpeta y no a la pac que apunta.

Una importación es de larga duración, así que install_solution la inicia y devuelve un identificador de trabajo; get_solution_import_status informa del progreso y del resultado, con el propio mensaje de Dataverse cuando falla.

Nota

publish_customizations es la misma acción que Publicar todas las personalizaciones en el portal maker, por lo que publica todo lo pendiente en el entorno, no solo tus propios cambios — en un entorno de desarrollo compartido que puede hacer que el trabajo a medio terminar de un compañero funcione. No es necesario después install_solutionde : importar una solución gestionada publica lo que aporta.

Tu propia solución

Los cambios que el servidor hace en un entorno — un rol de seguridad creado, un privilegio concedido o recuperado — van a una solución propia, registrada para ese entorno en .ppp/mcp.json. create_solution configura el editor y la solución una vez, en el entorno que construyes; hasta que uno se graba, las herramientas que personalizan Dataverse se niegan, porque un cambio hecho fuera de una solución queda varado en la solución predeterminada donde nada puede exportarlo.

El enlace también registra si la solución viaja sin gestión (por defecto, para entornos en los que también se trabaja) o gestionada (para entornos que solo la reciben). export_solution Abre la última parte de la versión y guarda el zip en el espacio de trabajo, push_solution y lo exporta e importa a otro entorno vinculado a la misma carpeta — desarrollo de build, push to test y producción. Una solución que depende del propio Power Portals Pro no se importa hasta que el destino también tiene esa.

Roles en el portal

Un rol de portal es mitad código y mitad datos. El desarrollador decide qué otorga el nombre "Dealer"; un administrador decide quién lo posee; nada une ambos excepto la cadena. Estos mantienen la mitad del Dataverse desde el mismo lugar donde se escribe la AddPortalRole llamada.

La cadena es toda la unión. Un error tipográfico entre el registro y el registro produce un rol que está registrado, asignable y no concede nada — sin error en ningún sitio. Dejar que el agente que acaba de escribir el registro cree el registro coincidente cierra esa brecha y check_setup detecta las discrepancias que ya existen: compara cada nombre de rol escrito en el proyecto con los registros y reporta los que faltan o están inactivos.

Una fila de Configuración de Rol del Portal decide qué nuevos usuarios registrados reciben un rol: cada uno de ellos, o aquellos que cumplen con los criterios de FetchXML. Los criterios se comprueban contra las reglas que el portal aplica antes de que se escriba la fila, porque el portal falla al cierre por criterios incorrectos y una regla rota parece exactamente una regla que no coincidió correctamente con nadie. Los administradores editan las mismas filas en la página de Configuración de Roles del portal.

Nota

Eliminar un rol tira todas sus asignaciones y nada recuerda quién lo tenía. Desactivar no otorga nada ni crea reclamación ninguna, pero conserva las asignaciones, así que es la forma reversible de desactivar un rol. Ambas herramientas de eliminación te piden que confirmes primero.

Sitios web con licencia

Un registro de Power Portals Pro Website es lo que licencia un portal servido desde una URL determinada. Estos los listan, añaden y mantienen — normalmente una vez por entorno, y de nuevo cuando un portal se traslada a su host de producción.

Esto es lo primero que debes comprobar cuando cada endpoint devuelve 402. Sin un registro activo coincidente, cada endpoint de datos en ese host rechaza la solicitud. Eliminar un registro lleva la licencia a partir de la siguiente petición, así que prefieres desactivar mientras investigas; la eliminación te pide confirmar.

Azure deployment

La mayoría de estas herramientas solo leen. Esas no necesitan más que Reader en la suscripción, y responden a las preguntas que hacen que la gente cueste días. check_deployment es la que hay que saber: compara lo que necesita el proyecto con lo que realmente tiene el servicio de aplicaciones, y nombra el fallo — una configuración obligatoria que solo existió en tus secretos de usuario, el entorno dejado en Desarrollo, WebSockets desactivados en un portal Blazor, un registro de Portal Website que no cubre el host desplegado, un portal que no puede acceder a Dataverse.

Siete herramientas cambian el Servicio de Aplicaciones: create_app_service, configure_app_service, set_app_service_settingsdeploy_to_app_service, , restart_app_service, y swap_slotscreate_deployment_slot . Cada una de ellas te pide confirmar y te dice cuánto costará antes de que respondas — la cifra mensual real para tu región, leída de la lista pública de precios de Azure, con una nota de que la lista minorista ignora cualquier Acuerdo Empresarial o reserva que tengas. Los nuevos recursos por defecto optan por el nivel más barato que pueda mantenerse caliente, para cualquier entorno, incluida la producción, considerando que escalar más tarde es un minuto y que sobreaprovisionar es una factura que nadie revisa.

En un plan Standard o Premium, un portal puede tener ranuras de despliegue, cada una ejecutándose contra su propio entorno Dataverse — una uat ranura contra UAT, mientras que producción contra producción. create_deployment_slot Crea una y la enlaza al entorno, así que cuando trabajas en UAT y pides un despliegue, la compilación va a la ranura UAT en lugar de a producción. Los ajustes que nombran un entorno están marcados para permanecer en su ranura, por lo que swap_slots pueden promover la compilación probada a producción y que se inicie contra los datos de producción. Se rechaza un swap cuando eso llevaría un entorno a otro.

Nota

Estos no usan la CLI de Azure y nunca leen ni cambian su estado de inicio de sesión. Ejecuta ppp-mcp azure login en la carpeta: al igual que la vinculación Dataverse, la suscripción pertenece solo a esa carpeta, así que varios proyectos pueden dirigirse a diferentes clientes a la vez. az account show No te dice nada sobre lo que harán estas herramientas.

Registros en la app Entra

Los dos registros que necesita un portal y los trabajos que les siguen. Estos son los pasos que retrasan la mayoría de las configuraciones: son dos registros separados en lugar de uno, la app de inicio de sesión necesita una URL de respuesta que lleve un puerto aleatorizado por la plantilla, y un secreto del cliente caduca un año después y detiene el portal que comienza con un error que nunca menciona Entra.

Las herramientas no tienen derechos propios. Cada llamada se realiza con un token delegado para la cuenta con la que iniciaste sesión, emitido a un cliente público que no guarda ningún secreto — así que cada operación tiene éxito exactamente cuando podrías haberla realizado manualmente en el portal, y se rechaza con un formulario 403 que nombra el rol de directorio que necesitarías cuando no pudiste. Inicia sesión como desarrollador de aplicaciones con cuenta o superior y estos funcionan; inicia sesión como cualquier otra persona y no pueden causar daño. No se solicitan permisos de API ni se concede consentimiento de administrador, porque ninguno de los registros necesita ninguno.

Ambas mitades, porque ninguna funciona por separado. Un registro de una app recibe un token; un usuario de una aplicación Dataverse decide qué puede hacer ese token. Un registro sin uno se autentica perfectamente y luego es rechazado por cada llamada, lo que se interpreta como una conexión rota en lugar de un objeto perdido — y un usuario de aplicación sin rol de seguridad es creado, visible, aparentemente bien y no puede hacer nada. create_dataverse_application_user hace la segunda mitad y asigna el rol en el mismo paso. Este es el único lugar donde el servidor escribe fuera de sus propias tres tablas, admitido porque un usuario de la aplicación es infraestructura y no datos del cliente; ninguna herramienta crea, cambia o elimina un registro empresarial.

Trabajan con registros que ya existen. Cada create_*_registration herramienta acepta un clientId, y con uno adopta ese registro en lugar de crearlo — añade un secreto, fusiona cualquier nueva URL de respuesta, escribe las credenciales donde lo pediste. La confirmación entonces dice añadir un secreto al registro existente en lugar de crearlo, así que nunca apruebas una operación y obtienes otra. Las herramientas que cambian un registro existente, add_app_registration_redirect_uri y add_app_registration_secret, toman también un ID de cliente y lo prefieren: los nombres de visualización no son únicos, y un inquilino con tres registros llamado "Portal" es normal.

Un secreto de cliente creado no se devuelve por defecto. Va directamente de la respuesta de Graph a los secretos de usuario del proyecto, a una aplicación de aplicación de aplicaciones, o a ambos, y la herramienta informa dónde fue y cuándo expira en lugar de cómo era. Cuando un secreto tiene que llegar a algún lugar donde el servidor no puede escribir — la máquina de un colega, un almacén secreto de CI, una bóveda en otra suscripción — lo pidas destination: "return" y se muestra el valor para que lo copies. La confirmación lo dice antes de que aceptes, y el resultado lleva la advertencia que lo merece: el secreto está entonces en la transcripción, así que trátalo como expuesto si esa transcripción está almacenada, y gíralo si tienes dudas. Los secretos se acuñan por defecto durante 24 meses — el periodo más largo que ofrece el portal de Entra — porque el fallo que realmente sufre este framework es un secreto caducado y no robado: el portal deja de empezar en una fecha que nadie ha notado, con un error que nunca menciona Entra. Ese límite pertenece a la interfaz del portal, no a la API, por lo que expiryMonths acepta cualquier plazo de hasta 120 (10 años) cuando preferirías rotar una vez cada cinco años antes que arriesgarte a una caída. No es el predeterminado, porque una credencial que ningún administrador podría haber creado a mano es algo sorprendente de encontrar — así que la confirmación te dice cuántos años pediste y que el portal no pudo producirla.

Una app puede iniciar sesión con un certificado en lugar de un secreto.add_app_registration_certificate crea un certificado en Key Vault cuya clave privada nunca podrá exportarse, y añade su mitad pública al registro. Vincula un entorno a esa app y ppp-mcp login --environment <url> --client-id <id> --certificate <url> el vault firma cada inicio de sesión para quien tenga Key Vault Crypto User en ella, de modo que ningún secreto esté en ninguna máquina. Para rotar, ejecuta la misma herramienta de nuevo;remove_app_registration_certificate retira el certificado antiguo cuando nada lo use.

Nota

Faltan deliberadamente dos cosas. Eliminar un registro puede hacer que el inicio de sesión de todas las aplicaciones en un tenant sea anulado y solo se puede recuperar dentro de un plazo de 30 días. Conceder el consentimiento del administrador es la operación que convierte un acto delegado estrecho en un permiso permanente para todo el tenant. Ninguno de los dos es necesario para poner en marcha un portal, así que ninguno se ofrece. Crear el usuario de la aplicación Dataverse para el nuevo id de cliente también es un paso aparte: la salida de la herramienta te da el comando.

Eliminar el secreto que caduca

Un secreto de cliente es la parte de un portal desplegado que deja de funcionar en una fecha que nadie apuntó. Estos lo eliminan o trasladan lo que queda a un lugar donde pueda rotarse sin necesidad de volver a desplegar.

Configura D365__ManagedIdentityId el id de cliente de la identidad — no el id de objeto o principal que muestra primero el portal de Azure — y asigna a ese id de cliente su propio usuario de aplicación Dataverse, con create_dataverse_application_user como cualquier otro. El portal entonces se conecta sin ningún secreto.

El remitente del correo

El portal envía correo de confirmación y restablecimiento de contraseña desde una dirección que debe resolverse a una cola o a un usuario habilitado en Dataverse. create_email_queue crea la cola, aprueba su buzón y ejecuta Test & Enable, informando del resultado; check_email_sender explica por qué un remitente no está entregando. Una cola, en lugar del buzón de una persona, es el remitente correcto para una dirección sin respuesta.

Importante

Dos cosas que no puede hacer por ti. La dirección necesita un buzón en Exchange Online — un buzón compartido, que no necesita licencia — y solo un Administrador Global de Office 365 o Exchange puede aprobarla. Cuando falta alguno de los dos, la herramienta indica cuál, y ejecutarlo de nuevo una vez arreglado termina el trabajo. Hasta que pase Test & Able, Dataverse acepta el correo del portal y no entrega nada — indistinguible de éxito desde el lado del portal, por eso la herramienta lo prueba en lugar de reportar un acabado limpio.

Trabajando en otros idiomas

El conocimiento que el servidor devuelve es inglés, y eso es deliberado. Tu asistente es quien lo lee — nunca ves una respuesta de herramienta directamente — así que se traduce para ti: pregunta en tu propio idioma, y responde en tu idioma. Lo que no debe traducir es el código. Los nombres de componentes, parámetros y columnas son en inglés en todos los proyectos, sea cual sea el idioma en el que esté la conversación, así que mantener la referencia en inglés es lo que impide que un asistente invente un nombre de parámetro traducido que no existe.

Nota

Las preguntas que nombran algo — “MainGrid Ansichten konfigurieren” — ya funcionan en cualquier idioma, porque los nombres de componentes son iguales en todas partes. Las herramientas también indican a tu asistente que busque en inglés, así que las preguntas que no nombran nada también funcionan.

Resolución de problemas