Skip to content
Back to search

mcp-private-lab

Copilot Studio agents in Teams calling private MCP servers (Azure / Google Cloud) with delegated Entra OAuth through Power Platform VNet Support

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/asevillano--mcp-private-lab/badge.svg)](/listings/asevillano--mcp-private-lab)

HTML

<a href="/listings/asevillano--mcp-private-lab"><img src="/api/listings/asevillano--mcp-private-lab/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readme.md · README · 1,647 lines
  1. # Agentes de Copilot Studio con servidores MCP privados, OAuth delegado y Teams
  2. Laboratorio que demuestra cómo conectar un agente de Copilot Studio publicado en Teams a un
  3. servidor MCP **sin exposición a Internet** y **con la identidad del usuario (OAuth delegado)**,
  4. sin usar el On-premises Data Gateway.
  5. El servidor MCP puede estar **en cualquier red alcanzable de forma privada desde Azure**: en una
  6. VNet de Azure, en **Google Cloud** o **on-premises**, conectado mediante VPN, ExpressRoute o
  7. Interconnect. El laboratorio incluye un MCP de prueba en Azure Container Apps para validar el
  8. patrón de extremo a extremo, pero ese despliegue es **opcional** (Paso 2A). Si ya existe un MCP,
  9. se usa el Paso 2B con los datos de la [sección 3.1](#31-datos-necesarios-del-servidor-mcp).
  10. | Documento | Contenido |
  11. |---|---|
  12. | Este README | Arquitectura, guía de configuración paso a paso, pruebas y troubleshooting |
  13. | [config/lab.config.example.json](./config/lab.config.example.json) | Plantilla de configuración. Se copia como `config/lab.config.json` (ignorado por git) con los valores de tu tenant; los scripts la leen (ver [Paso 0](#paso-0-preparar-la-configuración-local)) |
  14. > Laboratorio validado en un tenant de pruebas, con **datos sintéticos**. El entorno Power Platform
  15. > es de tipo *Production* por decisión expresa, pero es experimental: no implica que la arquitectura
  16. > esté certificada ni lista para producción. No se guardan secretos ni tokens en este repositorio.
  17. >
  18. > **Valores de ejemplo:** los identificadores del tenant de pruebas se han sustituido por marcadores
  19. > como `<TENANT_ID>` o `<MCP_HOST>`, que coinciden con los campos de `config/lab.config.json`. Las
  20. > evidencias exportadas (auditorías, diagnósticos) y la bitácora del montaje no se publican porque
  21. > contienen identificadores del tenant; las tablas de resultados citan el nombre del fichero original.
  22. ---
  23. ## Cómo funciona, explicado de forma sencilla
  24. **La idea en una frase:** Teams y Copilot Studio están en la nube de Microsoft, y el MCP está en
  25. Google Cloud **sin acceso desde Internet**. Para hablar con él, la llamada sale de Power Platform
  26. **por una red privada de Azure**, cruza a Google por un **túnel VPN cifrado** y llega al MCP **con la
  27. identidad del usuario**.
  28. A continuación, el recorrido de una pregunta en el agente **Asistente MCP GCP VNet** (opción 2C),
  29. desde que el usuario escribe en Teams hasta que ve la respuesta.
  30. **1. El usuario pregunta en Teams.**
  31. Por ejemplo, Aadi escribe «Comprueba la conexión con el MCP» en el chat del agente. Teams ya sabe quién
  32. es, así que no le pide iniciar sesión (SSO).
  33. **2. El agente decide usar la herramienta.**
  34. El agente de Copilot Studio lee sus instrucciones, ve que debe usar `iam_connection_check` y prepara
  35. una llamada al servidor MCP.
  36. **3. Obtiene un «pase» con la identidad del usuario.**
  37. Para llamar al MCP necesita un **token de Entra ID** que diga «soy Aadi y tengo permiso `MCP.Access`».
  38. - El usuario lo autoriza **una sola vez**, al pulsar *Conectar* la primera vez.
  39. - Desde entonces, su conexión guarda ese pase y lo renueva sola cuando caduca.
  40. Este paso va **directamente a Microsoft Entra ID**, no por la red privada, porque Entra es un servicio
  41. de Microsoft.
  42. **4. La llamada sale por la red privada de Azure.**
  43. El entorno de Power Platform tiene **VNet Support**: la llamada no sale «a Internet», sino desde un
  44. contenedor dentro de **nuestra subred de Azure** (10.92.x en Canada Central o 10.93.x en Canada East).
  45. **5. El DNS privado le dice adónde ir.**
  46. El contenedor pregunta: «¿cuál es la IP de `mcp-server-gcp-…run.app`?».
  47. - En Internet, ese nombre apuntaría a una IP pública de Google.
  48. - Nuestra **zona DNS privada de Azure** responde en cambio **`10.96.0.10`**, una IP privada dentro de
  49. Google Cloud.
  50. **6. La red de Azure sabe cómo llegar a esa IP.**
  51. Las subredes de Power Platform están conectadas a una VNet central (*hub*) que tiene un **VPN
  52. Gateway**. Mediante **BGP**, el gateway y Google se han intercambiado sus rutas, así que Azure sabe que
  53. `10.96.0.10` está «al otro lado del túnel».
  54. **7. La llamada cruza el túnel VPN.**
  55. Un **túnel IPsec cifrado**, en realidad dos para tener redundancia, une el VPN Gateway de Azure con el
  56. **HA VPN** de Google Cloud. Todo el tráfico entre las dos nubes viaja por ahí.
  57. **8. En Google Cloud, la IP privada entrega la llamada al MCP.**
  58. `10.96.0.10` es un **endpoint Private Service Connect**: una «puerta privada» de la VPC hacia los
  59. servicios de Google, que pasa la petición al servicio **Cloud Run** donde vive el MCP.
  60. - Cloud Run está configurado como **solo interno**: acepta la petición porque llega desde la red
  61. privada (la VPN).
  62. - Si alguien lo intentara desde Internet, recibiría un **404**.
  63. **9. Se comprueba el certificado.**
  64. El MCP presenta el certificado de `run.app`, emitido por **Google Trust Services**, una CA pública.
  65. Power Platform lo acepta; con un certificado de una CA interna rechazaría la conexión
  66. ([sección 2.6](#26-certificado-tls-del-mcp-qué-es-una-ca-y-qué-exige-power-platform)).
  67. **10. El MCP comprueba el pase del usuario.**
  68. Antes de hacer nada, el MCP verifica el token:
  69. - que lo ha firmado Entra ID y es de nuestro tenant;
  70. - que está vigente y es para esta API;
  71. - que tiene el permiso `MCP.Access`;
  72. - que lo pidió el **conector autorizado** y no otra aplicación;
  73. - que el usuario tiene el rol **`MCP.User`**, es decir, que pertenece al grupo piloto.
  74. Si todo es correcto, ejecuta la herramienta y responde con un JSON: quién es el usuario (`objectId`,
  75. modo `delegated`) y dónde se ejecuta el MCP (`runtime: gcp-cloud-run-europe-west1`). Si no, responde
  76. con 401 o 403 y no ejecuta nada.
  77. **11. La respuesta vuelve por el mismo camino.**
  78. MCP → endpoint PSC → túnel VPN → hub de Azure → subred de Power Platform → agente.
  79. **12. El agente la presenta en Teams.**
  80. El agente aplica las instrucciones de formato (bloque JSON con Origen, Estado, Modo y Datos
  81. sintéticos) y el usuario ve la respuesta en el chat.
  82. ```mermaid
  83. sequenceDiagram
  84. box transparent Microsoft 365 y Power Platform
  85. participant U as Usuario en Teams
  86. participant A as Agente Copilot Studio
  87. participant E as Entra ID
  88. end
  89. box transparent Azure · red privada
  90. participant S as Subred Power Platform<br/>10.92.x / 10.93.x
  91. participant H as Hub + VPN Gateway
  92. end
  93. box transparent Google Cloud · VPC privada
  94. participant G as HA VPN
  95. participant P as Endpoint PSC<br/>10.96.0.10
  96. participant M as MCP en Cloud Run<br/>(solo interno)
  97. end
  98. U->>A: 1. «Comprueba la conexión con el MCP» (SSO, sin iniciar sesión)
  99. A->>A: 2. Decide usar iam_connection_check
  100. A->>E: 3. Pide o renueva el token del usuario
  101. E-->>A: Token con permiso MCP.Access
  102. A->>S: 4. La llamada sale por VNet Support
  103. S->>S: 5. DNS privado: run.app → 10.96.0.10
  104. S->>H: 6. Ruta hacia Google aprendida por BGP
  105. H->>G: 7. Túnel IPsec cifrado (x2)
  106. G->>P: 8. Entrega a la IP privada
  107. P->>M: 8. Puerta privada hacia Cloud Run
  108. Note over S,M: 9. TLS con certificado de Google Trust Services (CA pública)
  109. M->>M: 10. Valida el token y el rol MCP.User<br/>y ejecuta la herramienta
  110. M-->>A: 11. Respuesta JSON por el mismo camino (PSC → VPN → hub → subred)
  111. A-->>U: 12. Respuesta con el formato de las instrucciones
  112. ```
  113. **Qué lo hace privado y seguro**
  114. | Pieza | Para qué sirve |
  115. |---|---|
  116. | **VNet Support de Power Platform** | La llamada sale desde **nuestra** red de Azure, sin necesitar el gateway on-premises |
  117. | **DNS privado** | Envía el nombre del MCP a su IP **privada**, no a la pública |
  118. | **VPN con BGP** | Une Azure y Google de forma **cifrada** y les dice cómo llegar a cada red |
  119. | **Private Service Connect + Cloud Run interno** | El MCP **solo acepta tráfico de la red privada**; desde Internet devuelve 404 |
  120. | **Certificado de CA pública** | Requisito de Power Platform para aceptar la conexión TLS |
  121. | **Token de Entra validado por el MCP** | Cada llamada va **con la identidad del usuario**, y solo se atiende si está autorizado |
  122. **En resumen:** la red decide **por dónde** viaja la llamada (siempre por caminos privados), y el token
  123. decide **quién** puede usar la herramienta (solo los usuarios autorizados, con su propia identidad).
  124. > **¿Y el agente de Azure (Asistente MCP Azure VNet)?** Sigue el mismo recorrido, pero más corto:
  125. > como su MCP está en Azure Container Apps, no hay VPN ni Google Cloud. En el paso 5, el DNS privado
  126. > devuelve la IP interna de ACA (`10.91.1.235`). En los pasos 6 a 8, la subred de Power Platform llega
  127. > al MCP directamente por el *peering* con la VNet del MCP. El resto, incluidos el token del usuario y
  128. > sus comprobaciones, es idéntico.
  129. >
  130. > **¿Y un MCP on-premises?** Igual que GCP, pero el túnel termina en el centro de datos (VPN
  131. > site-to-site o ExpressRoute) y el DNS reenvía al DNS corporativo.
  132. ---
  133. ## Índice
  134. 0. [Cómo funciona, explicado de forma sencilla](#cómo-funciona-explicado-de-forma-sencilla)
  135. 1. [Resumen](#1-resumen)
  136. 2. [Arquitectura](#2-arquitectura)
  137. 3. [Requisitos previos](#3-requisitos-previos)
  138. 4. [Guía de configuración](#4-guía-de-configuración)
  139. 5. [Pruebas y resultados](#5-pruebas-y-resultados)
  140. 6. [Troubleshooting](#6-troubleshooting)
  141. 7. [Recomendaciones](#7-recomendaciones)
  142. 8. [Recursos del laboratorio, costes y retirada](#8-recursos-del-laboratorio-costes-y-retirada)
  143. 9. [Contenido del repositorio](#9-contenido-del-repositorio)
  144. 10. [Referencias](#10-referencias)
  145. ---
  146. ## 1. Resumen
  147. **Problema:** en un conector personalizado de Power Platform no se conseguía combinar
  148. autenticación OAuth y conectividad privada. Al activar el On-premises Data Gateway desaparecía la
  149. opción OAuth.
  150. **Solución:** sustituir el gateway por **Power Platform Virtual Network (VNet) Support**. Las llamadas
  151. del conector al MCP salen por subredes de Azure delegadas al entorno, y desde ahí llegan al MCP por
  152. la red privada: peering en Azure, o VPN/ExpressRoute hacia GCP u on-premises. La autenticación
  153. OAuth se hace directamente contra Microsoft Entra ID. Las dos capacidades dejan de competir.
  154. **Resultado del laboratorio (20/11/2026):**
  155. | Capacidad | Estado |
  156. |---|---|
  157. | MCP sin entrada pública (Azure Container Apps interno) | ✅ Demostrado |
  158. | Ruta privada Power Platform → MCP **sin gateway**, desde las dos regiones del entorno | ✅ Demostrado |
  159. | OAuth **delegado** por usuario a través de esa ruta privada | ✅ Demostrado |
  160. | El tráfico del conector va **realmente** por las subredes delegadas (prueba de bloqueo) | ✅ Demostrado |
  161. | Agente publicado en **Teams**, con SSO en el chat 1:1 | ✅ Demostrado |
  162. | Segundo usuario con **su propia identidad** | ✅ Demostrado |
  163. | Usuario sin autorización rechazado | ⏳ Pendiente (E3) |
  164. | Renovación y revocación de tokens | ⏳ Pendiente (E4, E5) |
  165. | Conexión con un MCP **en Google Cloud** dentro de una VPC, sin acceso desde Internet, por VPN (opción 2C) | ✅ Demostrado: llamadas MCP delegadas desde Copilot Studio llegan al MCP de Cloud Run por la VPN |
  166. | Conexión con un MCP **on-premises** a través del hub | 📐 Mismo patrón que GCP (hub + VPN/ExpressRoute); se valida en el entorno de la organización con los datos de la sección 3.1 |
  167. El laboratorio prueba dos recorridos completos:
  168. - **Azure:** Power Platform → red privada de Azure → MCP en ACA.
  169. - **GCP:** Power Platform → red privada de Azure → VPN Gateway → HA VPN → VPC de GCP → MCP en Cloud Run.
  170. Un MCP on-premises usa el mismo tramo de hub y VPN o ExpressRoute que GCP; no cambia nada en Power
  171. Platform ni en Copilot Studio.
  172. ---
  173. ## 2. Arquitectura
  174. ### 2.1 Laboratorio desplegado
  175. ```mermaid
  176. flowchart LR
  177. U["Usuarios piloto<br/>grupo MCP-Lab-Pilot"] --> T["Microsoft Teams<br/>chat 1:1"]
  178. T -- "SSO" --> CS["Agente Copilot Studio<br/>Authenticate with Microsoft"]
  179. CS --> CC["Conector MCP (asistente)<br/>OAuth 2.0 Entra · credenciales del usuario final<br/>Streamable HTTP"]
  180. CC -. "Autorización / token / refresh<br/>(no usa la VNet)" .-> E["Microsoft Entra ID"]
  181. subgraph PP["Power Platform · entorno MCP Private Lab (Managed)"]
  182. CS
  183. CC
  184. EP["Enterprise Policy<br/>NetworkInjection"]
  185. end
  186. CC --> EP
  187. subgraph AZ["Azure · rg-mcp-lab"]
  188. subgraph CC1["Canada Central"]
  189. PPS["Subred delegada PP<br/>10.92.0.0/26"]
  190. end
  191. subgraph CE1["Canada East"]
  192. PPS2["Subred delegada PP<br/>10.93.0.0/26"]
  193. end
  194. subgraph NE["North Europe"]
  195. DNS["DNS privado ACA<br/>→ 10.91.1.235<br/>(enlazado a las 3 VNets)"]
  196. ACA["ACA interno (ILB)<br/>orígenes permitidos: ACA + subredes PP"]
  197. MCP["Servidor MCP /mcp<br/>valida firma, iss, aud, tid, exp<br/>+ scp + cliente permitido + rol MCP.User"]
  198. JOB["Job de prueba<br/>identidad administrada propia"]
  199. LAW["Log Analytics<br/>auditoría por petición"]
  200. end
  201. EP --> PPS
  202. EP --> PPS2
  203. PPS -->|"peering"| ACA
  204. PPS2 -->|"peering"| ACA
  205. PPS -.-> DNS
  206. PPS2 -.-> DNS
  207. ACA --> MCP
  208. JOB --> ACA
  209. MCP --> LAW
  210. end
  211. MCP -. "claves JWKS (salida HTTPS)" .-> E
  212. ```
  213. La región de Azure de las subredes **no se elige libremente**: la fija la ubicación del entorno
  214. Power Platform. Este laboratorio está en Canadá (pareja Canada Central + Canada East) porque la
  215. suscripción de pruebas no admitía West Europe (ver [6.1](#61-azure-y-despliegue)). Para un entorno en
  216. la geografía *Europe*, la pareja es West Europe + North Europe.
  217. ### 2.2 Arquitectura de referencia (MCP en Google Cloud u on-premises)
  218. ```mermaid
  219. flowchart LR
  220. subgraph M365["Microsoft 365 / Power Platform"]
  221. T["Teams"] --> A["Agente Copilot Studio<br/>SSO Entra"]
  222. A --> C["Conector MCP<br/>OAuth delegado Entra"]
  223. end
  224. C -. "OAuth/token hacia Entra" .-> ENTRA["Microsoft Entra ID"]
  225. C -->|"Subnet injection"| S1
  226. C -->|"Subnet injection"| S2
  227. subgraph AZ["Azure (suscripción de la organización)"]
  228. subgraph R1["Región 1 de la pareja PP"]
  229. S1["Spoke PP<br/>subred delegada"]
  230. end
  231. subgraph R2["Región 2 de la pareja PP"]
  232. S2["Spoke PP<br/>subred delegada"]
  233. end
  234. subgraph HUB["Hub"]
  235. RES["Azure DNS Private Resolver<br/>reenvío a Cloud DNS / DNS corporativo"]
  236. GW["Front privado MCP<br/>APIM interno / Application Gateway<br/>certificado de CA pública, validate-jwt"]
  237. VPN["VPN Gateway / interconexión"]
  238. end
  239. S1 --> HUB
  240. S2 --> HUB
  241. end
  242. GW --> VPN
  243. VPN <-->|"VPN IPsec HA / Interconnect"| GCPVPN["Cloud VPN / Router"]
  244. VPN <-->|"VPN S2S / ExpressRoute"| ONP["Red corporativa<br/>(on-premises)"]
  245. subgraph GCP["Google Cloud (organización)"]
  246. GCPVPN --> F5["F5 / ILB interno"] --> MCPS["Servidores MCP<br/>validan el token de Entra"]
  247. CDNS["Cloud DNS privado"]
  248. end
  249. subgraph OP["Centro de datos (opcional)"]
  250. ONP --> MCPO["Servidores MCP on-premises<br/>validan el token de Entra"]
  251. ODNS["DNS corporativo"]
  252. end
  253. RES -. "forwarding" .-> CDNS
  254. RES -. "forwarding" .-> ODNS
  255. ```
  256. Claves de la arquitectura de referencia:
  257. - **Sin gateway:** la ruta privada la proporciona VNet Support.
  258. - **Las subredes delegadas son *spokes* de un hub** que tiene la puerta de enlace VPN o ExpressRoute
  259. (*gateway transit*). Las rutas hacia GCP y on-premises llegan por BGP.
  260. - **Certificado TLS de CA pública** en el punto de entrada del MCP. Es un requisito **oficial**:
  261. Power Platform exige un certificado con la cadena completa de una CA reconocida y no admite añadir
  262. CA raíz propias. Qué significa y cómo comprobarlo, en la
  263. [sección 2.6](#26-certificado-tls-del-mcp-qué-es-una-ca-y-qué-exige-power-platform).
  264. - **DNS:** las subredes delegadas usan el DNS configurado en **su** VNet. El FQDN del MCP debe
  265. resolverse a una IP privada desde **las dos** regiones de la pareja; por ejemplo, con Private
  266. Resolver y reenvío a Cloud DNS o al DNS corporativo. Ese DNS **no puede cambiarse** con la
  267. política vinculada.
  268. - **Identidad única Entra:** los MCP de GCP u on-premises validan el mismo contrato JWT que el MCP
  269. del laboratorio.
  270. - **APIM** (recomendado si hay varios MCP): centraliza TLS público, `validate-jwt`, cuotas y logs.
  271. ### 2.3 Dónde puede estar el servidor MCP
  272. | Ubicación del MCP | Conectividad desde las subredes de Power Platform | DNS | Paso 2 |
  273. |---|---|---|---|
  274. | **MCP de prueba en ACA** (laboratorio) | Peering directo con la VNet del MCP | Zona privada de ACA enlazada a las VNets de Power Platform | 2A (opcional) |
  275. | **MCP de prueba en Cloud Run (GCP)** (laboratorio, validado) | Gateway transit por el VPN Gateway del hub + HA VPN hacia la VPC; Cloud Run interno a través de un endpoint PSC | Zona privada de Azure con el nombre exacto `…run.app` → IP del endpoint PSC | 2C (opcional) |
  276. | **Otra VNet de Azure** (AKS, App Service con Private Endpoint, VM, APIM interno…) | Peering directo, o peering con el hub | Zona privada enlazada, o Private Resolver | 2B |
  277. | **Google Cloud** | Peering con el hub + VPN HA o Cross-Cloud Interconnect hacia GCP (*gateway transit*) | Private Resolver con reenvío al *inbound forwarder* de Cloud DNS | 2B |
  278. | **On-premises** | Peering con el hub + VPN site-to-site o ExpressRoute (*gateway transit*) | Private Resolver con reenvío al DNS corporativo, o DNS corporativo en la VNet | 2B |
  279. En todos los casos se aplican los mismos requisitos al MCP: Streamable HTTP, certificado de CA pública,
  280. reglas de firewall que admitan las subredes de Power Platform y validación del token de Entra
  281. (ver [3.1](#31-datos-necesarios-del-servidor-mcp)).
  282. ### 2.4 Qué significa «privado» en esta solución
  283. - El MCP **no tiene entrada pública**. En el laboratorio es un entorno de Container Apps interno
  284. (`ingress.external: true` significa «accesible desde la VNet», no desde Internet). En GCP u
  285. on-premises, es una IP privada detrás del F5 o del balanceador interno.
  286. - **No pasan por la VNet:** el inicio de sesión y la obtención de tokens con Entra ID, ni el propio
  287. servicio de Teams o Copilot Studio. Son servicios SaaS de Microsoft. Lo que no se expone son
  288. **los servidores y sistemas de la organización**.
  289. ### 2.5 Control de acceso por capas
  290. | Capa | Control | Dónde se configura | Verificado |
  291. |---|---|---|---|
  292. | Red | Solo las subredes autorizadas llegan al MCP | Laboratorio: `ipSecurityRestrictions` de ACA. MCP externo: firewall de GCP, firewall on-premises o NSG | ✅ Prueba C2 |
  293. | Entorno Power Platform | Solo los miembros del grupo de seguridad del entorno | Grupo de seguridad del entorno | ⏳ E3 |
  294. | Agente | Con quién se comparte el agente | Copilot Studio → Compartir | ✅ E2 |
  295. | Conector | Quién puede leer el conector para crear su conexión | Dataverse: equipo + uso compartido del conector | ✅ E2 |
  296. | Entra ID | Solo los usuarios con el rol `MCP.User` obtienen token | Asignación obligatoria en la aplicación API | ⏳ E3/E5 |
  297. | Servidor MCP | Exige scope `MCP.Access`, cliente del conector permitido y rol `MCP.User` | Laboratorio: código (`src/auth.mjs`) y variables de la app. MCP externo: su validación de tokens | ✅ Pruebas locales y C1 |
  298. Registros de aplicación de Entra que intervienen (mezclarlos es la causa más habitual de fallos):
  299. | Aplicación | Función |
  300. |---|---|
  301. | **API del MCP** (`mcp-lab-api`) | Recurso protegido. Scope delegado `MCP.Access`; roles `MCP.User` (usuarios) y `MCP.Probe` (job de prueba); asignación obligatoria |
  302. | **Cliente OAuth del conector** (`mcp-lab-connector`) | La usa el conector para pedir tokens en nombre del usuario. Redirect URI = callback del asistente MCP |
  303. | *App SSO del agente* (solo contingencia) | Solo es necesaria si el agente usa *Authenticate manually*. No es necesaria con *Authenticate with Microsoft* |
  304. ### 2.6 Certificado TLS del MCP: qué es una CA y qué exige Power Platform
  305. Este requisito es fácil de pasar por alto y bloquea la conexión aunque la red, el DNS y OAuth estén
  306. bien configurados. **No impide la solución**: solo condiciona qué certificado debe presentar el MCP.
  307. **Qué es un certificado TLS.** Cuando un cliente se conecta por HTTPS, el servidor le presenta un
  308. certificado: un documento digital que dice «soy `mcp.ejemplo.es`». Sirve para dos cosas: que el
  309. cliente compruebe que habla con el servidor correcto y no con un impostor, y cifrar la comunicación.
  310. **Qué es una CA (autoridad de certificación).** Es la entidad que **emite y firma** los
  311. certificados y garantiza que cada uno pertenece a quien dice. Una analogía: el certificado es el
  312. «DNI» del servidor y la CA es quien lo expide. El cliente solo acepta el certificado si lo ha firmado
  313. una CA **en la que confía**. Cada sistema operativo, navegador o servicio trae una lista de CA de
  314. confianza preinstalada: su *almacén de confianza*.
  315. **CA pública y CA privada (interna)**
  316. | | CA pública | CA privada o interna |
  317. |---|---|---|
  318. | Quién es | Empresas reconocidas internacionalmente: DigiCert, Sectigo, GlobalSign, Let's Encrypt, Microsoft… | La propia organización, por ejemplo la CA corporativa o la de un proveedor de servicios (Active Directory Certificate Services, PKI propia…) |
  319. | Quién confía en ella | Prácticamente todos los sistemas: navegadores, Windows, Azure, **Power Platform**. Viene preinstalada | Solo los equipos en los que la organización ha instalado su certificado raíz |
  320. | Qué pide para emitir un certificado | Demostrar que controlas el **dominio público**, normalmente con un registro DNS | Lo que decida la organización |
  321. | Coste | Desde gratis (Let's Encrypt) hasta cientos de euros al año | Interno |
  322. | Uso típico | Servicios que deben ser aceptados por clientes externos | Servicios internos usados solo por equipos corporativos |
  323. **Cadena de certificados.** El certificado del servidor suele estar firmado por una CA
  324. **intermedia**, que a su vez está firmada por la CA **raíz**. El servidor debe enviar su certificado
  325. **y los intermedios** (la *cadena completa*) para que el cliente pueda llegar hasta una raíz de
  326. confianza. Ejemplo real: `learn.microsoft.com` presenta un certificado emitido por *Microsoft TLS G2
  327. ECC CA OCSP 06* (intermedia), cuya raíz es *DigiCert Global Root G3* (pública).
  328. **Qué exige Power Platform.** Las llamadas del conector al MCP salen de contenedores de Power Platform
  329. cuyo almacén de confianza **solo incluye CA públicas y no se puede ampliar**. Lo indica la
  330. documentación oficial de Microsoft, en la pregunta frecuente de VNet Support sobre certificados de CA
  331. no reconocidas:
  332. > 📄 **Microsoft Learn — Azure Virtual Network support for Power Platform, FAQ:**
  333. > [*My on-premises endpoint TLS certificates aren't signed by well-known root certification
  334. > authorities (CA). Do you support unknown certificates?*](https://learn.microsoft.com/en-us/power-platform/admin/vnet-support-overview#my-on-premises-endpoint-tls-certificates-arent-signed-by-well-known-root-certification-authorities-ca-do-you-support-unknown-certificates)
  335. >
  336. > *«No. Power Platform requires the endpoint to present a TLS certificate with the complete chain.
  337. > You can't add your custom root CA to the list of well-known CAs.»*
  338. >
  339. > Traducción: «No. Power Platform exige que el endpoint presente un certificado TLS con la cadena
  340. > completa. No se puede añadir una CA raíz propia a la lista de CA reconocidas.»
  341. Por tanto:
  342. | Si el MCP presenta… | Resultado |
  343. |---|---|
  344. | Certificado de CA pública, cadena completa, nombre (SAN) = FQDN del MCP, vigente | ✅ Funciona |
  345. | Certificado de una CA interna (corporativa o del proveedor) | ❌ Falla la conexión TLS, aunque todo lo demás esté bien |
  346. | Certificado autofirmado, caducado, sin intermedios o con otro nombre | ❌ Falla la conexión TLS |
  347. **Certificado público no significa servidor expuesto.** Un certificado de CA pública solo exige que el
  348. nombre del MCP pertenezca a un **dominio público registrado** de la organización (por ejemplo
  349. `mcp.<dominio>.es`; no sirven nombres como `.local` o `.corp`). Ese nombre puede resolverse
  350. **solo dentro de la red privada** (DNS dividido o *split-horizon*): la CA valida la propiedad del
  351. dominio con un registro en el DNS público, sin conectarse al servidor. El MCP sigue sin entrada pública.
  352. **Cómo saber qué certificado presenta el MCP**
  353. 1. **Comprobación definitiva, desde Power Platform** (Paso 4.5): `pp-vnet-diagnostics.ps1` devuelve,
  354. en `tls`, el emisor (`certificate.issuer`), si es autofirmado (`isSelfSigned`), si ha caducado
  355. (`isExpired`) y los errores de validación (`sslErrors`). `sslErrors: None` significa que Power
  356. Platform acepta el certificado.
  357. 2. **Comprobación previa, desde un equipo de la red interna** que llegue al MCP:
  358. ```powershell
  359. $fqdn = 'mcp.ejemplo.es' # nombre del certificado (dato 1 de la sección 3.1)
  360. $target = '10.20.30.40' # IP privada del MCP o del F5 (dato 3); o el propio FQDN
  361. $tcp = [Net.Sockets.TcpClient]::new($target, 443)
  362. $ssl = [Net.Security.SslStream]::new($tcp.GetStream(), $false, { $true })
  363. $ssl.AuthenticateAsClient($fqdn)
  364. $cert = [Security.Cryptography.X509Certificates.X509Certificate2]$ssl.RemoteCertificate
  365. $chain = [Security.Cryptography.X509Certificates.X509Chain]::new(); [void]$chain.Build($cert)
  366. [pscustomobject]@{
  367. Nombre = ($cert.DnsNameList.Unicode | Select-Object -First 3) -join ', '
  368. Emisor = $cert.Issuer
  369. Raiz = $chain.ChainElements[-1].Certificate.Subject
  370. Caduca = $cert.NotAfter
  371. TLS = $ssl.SslProtocol
  372. } | Format-List
  373. $ssl.Dispose(); $tcp.Dispose()
  374. ```
  375. Si **Raíz** es una CA pública conocida (DigiCert, Sectigo, GlobalSign, ISRG/Let's Encrypt,
  376. Microsoft…), es válido. Si contiene el nombre de la organización (por ejemplo *Contoso Root CA*), es
  377. una **CA interna**. No basta con que el equipo diga que la cadena es válida: los equipos
  378. corporativos suelen confiar también en la CA interna, y Power Platform no.
  379. **Qué hacer si el MCP usa una CA interna**
  380. | Opción | Qué implica |
  381. |---|---|
  382. | **1. Certificado de CA pública en el F5 o en el MCP** (la más sencilla) | Usar un nombre de un dominio público de la organización con DNS dividido, y emitir el certificado con una CA pública. Si los MCP ya se publicaban en Internet a través del F5, **probablemente ya exista** un certificado público reutilizable con el mismo nombre |
  383. | **2. Front privado en Azure** (APIM interno o Application Gateway) | El front presenta un certificado público a Power Platform y reenvía al MCP aceptando la CA interna. Encaja si además se quieren centralizar varios MCP (sección 2.2) |
  384. En el laboratorio, el MCP de ACA presenta un certificado de una CA pública de Microsoft
  385. (*Microsoft TLS G2 RSA CA OCSP 02*), y los diagnósticos desde Power Platform lo validaron en las dos
  386. regiones (`sslErrors: None`).
  387. ---
  388. ## 3. Requisitos previos
  389. | Requisito | Detalle |
  390. |---|---|
  391. | Roles | Propietario o colaborador de la suscripción Azure; administrador de Power Platform; administrador de aplicaciones de Entra (o equivalente) para crear aplicaciones y conceder consentimiento |
  392. | Herramientas | Azure CLI (probado con 2.93), Bicep, Power Platform CLI `pac` (2.15), Node.js 22+, PowerShell 7 |
  393. | Licencias | Capacidad de Dataverse para un entorno; Managed Environments; Copilot Studio; usuarios con Teams |
  394. | Regiones | Poder crear VNets en **las dos** regiones Azure que corresponden a la ubicación del entorno Power Platform ([tabla oficial](https://learn.microsoft.com/en-us/power-platform/admin/vnet-support-overview#supported-regions)) |
  395. | Conectividad (MCP externo) | Hub de Azure con VPN Gateway o ExpressRoute hacia GCP u on-premises, y rangos IP **sin solapamiento** entre Azure, GCP y on-premises |
  396. | Políticas del tenant | Que Microsoft 365 y Teams permitan instalar agentes creados por la organización |
  397. ### 3.1 Datos necesarios del servidor MCP
  398. Si el MCP ya existe (GCP, on-premises u otra red), hay que pedir estos datos al equipo propietario
  399. **antes de empezar**. La tercera columna muestra el valor del laboratorio como
  400. ejemplo.
  401. | # | Dato | Ejemplo (laboratorio) | Para qué se usa |
  402. |---|---|---|---|
  403. | **Endpoint** ||||
  404. | 1 | URL completa del MCP (HTTPS, FQDN y ruta) | `https://<MCP_HOST>/mcp` | *Server URL* del asistente MCP (Paso 6) |
  405. | 2 | Transporte MCP | Streamable HTTP | Copilot Studio **solo** admite Streamable HTTP; SSE ya no está soportado |
  406. | 3 | IP privada (VIP) del punto de entrada y puerto | `10.91.1.235:443` | Diagnóstico TCP y reglas de firewall |
  407. | **TLS** ||||
  408. | 4 | Certificado: emisor, CA raíz, SAN y cadena completa | Emisor *Microsoft TLS G2 RSA CA OCSP 02* (CA pública) | **Requisito:** CA pública, SAN = FQDN del punto 1, cadena completa, TLS 1.2 o superior. Ver [2.6](#26-certificado-tls-del-mcp-qué-es-una-ca-y-qué-exige-power-platform) |
  409. | **DNS** ||||
  410. | 5 | Zona DNS del FQDN y servidores que la resuelven | Zona privada de ACA (Azure DNS) | Reglas de reenvío del Private Resolver o DNS de las VNets de Power Platform |
  411. | 6 | IP del *inbound forwarder* de Cloud DNS o del DNS corporativo | — | Destino del reenvío condicional |
  412. | **Red** ||||
  413. | 7 | Rangos IP de la red del MCP (GCP, on-premises) | `10.91.0.0/16` | Comprobar que no se solapan; rutas BGP |
  414. | 8 | Tipo de interconexión con Azure y quién la gestiona | Peering de VNet | VPN HA, Interconnect, VPN S2S o ExpressRoute; hub existente o nuevo |
  415. | 9 | Datos de la VPN: IP pública del extremo, ASN BGP, parámetros IKE/IPsec | — | Local Network Gateway y conexión. **La clave compartida se intercambia por un canal seguro, nunca en documentos** |
  416. | 10 | Firewall delante del MCP | Restricción de IP de ACA | Abrir TCP 443 **desde las dos subredes delegadas** de Power Platform (Paso 4) |
  417. | 11 | SNAT o NAT intermedios | Ninguno | Si hay NAT, la lista de IP de origen permitidas cambia |
  418. | **Autenticación** ||||
  419. | 12 | ¿El MCP puede validar tokens de Entra ID? | Sí (`src/auth.mjs`) | Contrato de la tabla siguiente |
  420. | 13 | Si usa otro proveedor OAuth: URL de autorización, de token y de refresh | — | Asistente MCP. Esas URL deben ser **públicamente accesibles**, porque OAuth no pasa por la VNet |
  421. | 14 | Salida del MCP hacia `login.microsoftonline.com` (claves JWKS) | Sí | Sin ella, el MCP no puede validar firmas |
  422. | **Operación** ||||
  423. | 15 | Endpoint de salud y respuesta sin token | `/healthz`; `POST /mcp` sin token → 401 | Diagnóstico |
  424. | 16 | Dónde se registran las llamadas y si incluyen un identificador de petición | Log Analytics con `requestId` | Correlación de pruebas y troubleshooting |
  425. | 17 | Contacto técnico y ventana de cambios | — | Coordinación de las pruebas de bloqueo |
  426. **Contrato de validación del token** que debe implementar el MCP (el del laboratorio está en
  427. [src/auth.mjs](./src/auth.mjs)):
  428. | Claim | Valor esperado | Si no coincide |
  429. |---|---|---|
  430. | Firma | RS256 con las claves JWKS de `https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys` | 401 |
  431. | `iss` | `https://login.microsoftonline.com/<tenant>/v2.0` | 401 |
  432. | `aud` | appId de la API del MCP (Paso 1) | 401 |
  433. | `tid` | ID del tenant | 401 |
  434. | `exp`, `iat` | Token vigente | 401 |
  435. | `scp` | Contiene `MCP.Access` | 403 |
  436. | `azp` | Client ID del cliente OAuth del conector (Paso 5) | 403 |
  437. | `roles` | Contiene `MCP.User` | 403 |
  438. | Identidad del usuario | `oid` (y `upn`, si se necesita) para aplicar los permisos sobre los sistemas de la organización | — |
  439. > **Consejo para Windows:** en `az rest`, pasa siempre el cuerpo JSON en un fichero (`--body "@fichero.json"`)
  440. > y añade `--headers Content-Type=application/json`. El JSON escrito directamente en la línea de
  441. > comandos falla por el entrecomillado (ver [6.1](#61-azure-y-despliegue)).
  442. ---
  443. ## 4. Guía de configuración
  444. | Paso | Qué se configura | Dónde | Tiempo aprox. |
  445. |---|---|---|---|
  446. | 0 | Repositorio y configuración local (`config/lab.config.json`) | PowerShell | 5 min |
  447. | 1 | Identidades en Entra ID | CLI | 10 min |
  448. | 2 | Servidor MCP: **2A** MCP de prueba en ACA (opcional, laboratorio), **2B** preparar un MCP existente (GCP, on-premises u otra red) **o 2C** MCP de prueba en GCP por VPN (opcional, laboratorio) | CLI / equipo propietario del MCP | 20 min / variable / 1,5 h |
  449. | 3 | Entorno Power Platform y Managed Environment | CLI | 15 min |
  450. | 4 | VNet Support y conectividad con el MCP | CLI (+ equipo de red si el MCP es externo) | 15 min + hasta 30 min de propagación |
  451. | 5 | Aplicación cliente OAuth del conector | CLI | 5 min |
  452. | 6 | Agente y herramienta MCP en Copilot Studio | Portal + CLI | 15 min |
  453. | 7 | Publicación en Teams | Portal | 10 min |
  454. | 8 | Acceso de otros usuarios | CLI + Portal | 10 min |
  455. > Los pasos marcados **[Laboratorio]** solo se aplican al MCP de prueba en ACA. Los marcados
  456. > **[MCP externo]** solo se aplican cuando el MCP está en GCP, on-premises u otra red. El resto es común.
  457. ### Paso 0. Preparar la configuración local
  458. Todos los comandos se ejecutan desde la carpeta del repositorio, con Azure CLI conectado al tenant y a
  459. la suscripción en los que se va a montar la solución (`az login`, `az account set`):
  460. ```powershell
  461. git clone https://github.com/asevillano/mcp-private-lab.git
  462. Set-Location mcp-private-lab
  463. Copy-Item config\lab.config.example.json config\lab.config.json
  464. ```
  465. [config/lab.config.json](./config/lab.config.example.json) guarda los valores de **tu** tenant y está
  466. en `.gitignore`, así que nunca se sube al repositorio. Los scripts de `tools/` e `infra/gcp/` leen de
  467. él cualquier parámetro que no se les pase (cada parámetro se puede seguir pasando a mano). Si
  468. falta un valor, o sigue con su marcador `<...>`, el script se detiene e indica qué campo completar.
  469. Para usar otro fichero, define `$env:MCP_LAB_CONFIG` con su ruta.
  470. Los campos se rellenan a medida que avanza la guía:
  471. | Campos de `config/lab.config.json` | Cuándo se completan |
  472. |---|---|
  473. | `tenantId`, `subscriptionId` | Ahora (`az account show --query "{tenantId:tenantId, subscriptionId:id}"`) |
  474. | `azure.resourceGroup`, `azure.location`, `azure.namePrefix`, `azure.foundationDeployment` | Ahora: nombres que quieras usar (se pueden dejar los de ejemplo) |
  475. | `entra.apiClientId`, `entra.apiObjectId`, `entra.apiServicePrincipalId` | Paso 1.1 |
  476. | `entra.pilotGroupObjectId`, `entra.pilotGroupName` | Paso 1.3 |
  477. | `azure.acrName`, `azure.logAnalyticsWorkspaceId`, `azure.probeClientId`, `mcp.host` | Paso 2A.2 (salidas del despliegue) |
  478. | `powerPlatform.environmentId`, `powerPlatform.orgUrl` | Paso 3 |
  479. | `powerPlatform.regions`, `powerPlatform.delegatedSubnetCidrs` | Paso 4 (pareja de regiones del entorno y subredes delegadas) |
  480. | `entra.connectorClientId` | Paso 5 |
  481. | `powerPlatform.connectorDisplayName` | Paso 6 (nombre del conector que crea el asistente MCP) |
  482. | `gcp.*` | Paso 2C (solo si se monta el MCP de prueba en GCP) |
  483. Carga en la sesión las variables que usan los comandos de la guía. **Vuelve a ejecutarlo cada vez
  484. que completes campos nuevos:**
  485. ```powershell
  486. $cfg = Get-Content config\lab.config.json -Raw | ConvertFrom-Json
  487. $TENANT = $cfg.tenantId
  488. $RG = $cfg.azure.resourceGroup
  489. $GROUP = $cfg.entra.pilotGroupObjectId
  490. $API_APP = $cfg.entra.apiClientId
  491. $API_OBJ = $cfg.entra.apiObjectId
  492. $API_SP = $cfg.entra.apiServicePrincipalId
  493. $ENV_ID = $cfg.powerPlatform.environmentId
  494. $MCP_HOST = $cfg.mcp.host
  495. ```
  496. > Las plantillas del repositorio ([infra/api-registration.json](./infra/api-registration.json),
  497. > [infra/connector-client-registration.json](./infra/connector-client-registration.json),
  498. > [infra/probe-role-assignment.json](./infra/probe-role-assignment.json) y
  499. > [connector/mcp-openapi.yaml](./connector/mcp-openapi.yaml)) contienen marcadores `<...>`. Los
  500. > comandos de la guía generan una copia rellenada en `%TEMP%`, de modo que los ficheros del
  501. > repositorio no cambian ni acaban con datos del tenant.
  502. ### Paso 1. Identidades en Entra ID
  503. **1.1 Aplicación de la API del MCP**
  504. ```powershell
  505. az ad app create --display-name 'mcp-lab-api' --sign-in-audience AzureADMyOrg
  506. ```
  507. Anota `appId` e `id`, y el `id` del service principal que crea el segundo comando; guárdalos en
  508. `entra.apiClientId`, `entra.apiObjectId` y `entra.apiServicePrincipalId` y recarga las variables
  509. (Paso 0). [infra/api-registration.json](./infra/api-registration.json) define:
  510. - el scope delegado `MCP.Access`;
  511. - los roles `MCP.User`, para usuarios, y `MCP.Probe`, para el job de prueba;
  512. - tokens v2;
  513. - `identifierUris` = `api://<API_APP_ID>`, que el comando rellena con tu `appId`.
  514. ```powershell
  515. az ad sp create --id $API_APP --query id -o tsv # guárdalo en entra.apiServicePrincipalId y recarga antes de 1.2
  516. (Get-Content infra\api-registration.json -Raw).Replace('<API_APP_ID>', $API_APP) |
  517. Set-Content "$env:TEMP\api-registration.json" -Encoding utf8
  518. az rest --method PATCH --headers Content-Type=application/json `
  519. --url "https://graph.microsoft.com/v1.0/applications/$API_OBJ" --body "@$env:TEMP\api-registration.json"
  520. ```
  521. **1.2 Exigir asignación**, para que Entra solo emita tokens a quien tenga un rol:
  522. ```powershell
  523. '{"appRoleAssignmentRequired": true}' | Set-Content "$env:TEMP\sp.json" -Encoding ascii
  524. az rest --method PATCH --headers Content-Type=application/json `
  525. --url "https://graph.microsoft.com/v1.0/servicePrincipals/$API_SP" --body "@$env:TEMP\sp.json"
  526. ```
  527. **1.3 Grupo piloto y rol `MCP.User`**
  528. ```powershell
  529. az ad group create --display-name 'MCP-Lab-Pilot' --mail-nickname 'mcp-lab-pilot' --query id -o tsv
  530. # guarda el id en entra.pilotGroupObjectId (y el nombre en entra.pilotGroupName) y recarga las variables
  531. az ad group member add --group $GROUP --member-id <objectId-del-usuario>
  532. @{ principalId = $GROUP; resourceId = $API_SP; appRoleId = '8d0f6a2e-5b8c-4f43-9e1a-2c7b6d4e9a31' } |
  533. ConvertTo-Json | Set-Content "$env:TEMP\role.json" -Encoding ascii
  534. az rest --method POST --headers Content-Type=application/json `
  535. --url "https://graph.microsoft.com/v1.0/servicePrincipals/$API_SP/appRoleAssignedTo" --body "@$env:TEMP\role.json"
  536. ```
  537. > El grupo se crea **sin correo**. Funciona en Entra, Power Platform y Dataverse, pero el nuevo
  538. > diálogo *Compartir* de Copilot Studio no lo encuentra (ver [6.5](#65-acceso-de-otros-usuarios)).
  539. ### Paso 2. Servidor MCP
  540. Elige **una** de las opciones. 2A y 2C pueden convivir en el mismo laboratorio, como ocurre en este: un
  541. agente usa el MCP de ACA y otro, el de GCP.
  542. #### 2A. [Laboratorio] MCP de prueba en Azure Container Apps (opcional)
  543. Sirve para validar el patrón completo sin depender de los sistemas de la organización. Si vas a conectar un MCP
  544. existente, salta a [2B](#2b-mcp-externo-preparar-un-mcp-existente-gcp-on-premises-u-otra-red).
  545. El servidor ([src/](./src/)) usa el SDK oficial de MCP con transporte Streamable HTTP sin estado y
  546. una sola herramienta sintética, `iam_connection_check`. Rechaza cualquier petición sin un token de
  547. Entra válido y registra cada llamada **sin incluir tokens**. Su validación de tokens es la
  548. implementación de referencia del contrato de la [sección 3.1](#31-datos-necesarios-del-servidor-mcp).
  549. **2A.1 Pruebas locales**
  550. ```powershell
  551. npm install --ignore-scripts
  552. npm test # 18/18 pruebas: firma, iss, aud, tid, exp, scope, cliente, rol y protocolo MCP
  553. ```
  554. **2A.2 Infraestructura base** ([infra/main.bicep](./infra/main.bicep)): VNet, entorno ACA **interno**,
  555. zona DNS privada, ACR sin usuario administrador, dos identidades administradas (runtime y prueba) y
  556. Log Analytics.
  557. ```powershell
  558. az group create --name $RG --location westeurope --tags purpose=MCP-OAuth-private-PoC data=synthetic-only
  559. az deployment group create -g $RG -n $cfg.azure.foundationDeployment --template-file infra\main.bicep `
  560. --parameters location=$($cfg.azure.location) namePrefix=$($cfg.azure.namePrefix) registryNamePrefix=$($cfg.azure.registryNamePrefix) `
  561. tenantId=$TENANT `
  562. apiClientId=$API_APP imageName=$($cfg.mcp.imageName) imageTag=$($cfg.mcp.imageTag) `
  563. --query "properties.outputs.{acrName:registryName.value, logAnalyticsWorkspaceId:logAnalyticsCustomerId.value, probeClientId:probeClientId.value, probePrincipalId:probePrincipalId.value, acaDomain:environmentDomain.value}"
  564. ```
  565. Guarda las salidas en `azure.acrName`, `azure.logAnalyticsWorkspaceId` y `azure.probeClientId`, y
  566. pon `mcp.host` = `<mcp.appName>.<acaDomain>` (por ejemplo, `mcp-server.<ACA_DEFAULT_DOMAIN>`). Recarga
  567. las variables.
  568. **2A.3 Imagen del contenedor**, construida en ACR (no requiere Docker local):
  569. ```powershell
  570. az acr build --registry $cfg.azure.acrName --image "$($cfg.mcp.imageName):$($cfg.mcp.imageTag)" --file Dockerfile . --no-logs
  571. ```
  572. **2A.4 Rol `MCP.Probe` para la identidad de prueba**, con la salida `probePrincipalId` del paso 2A.2:
  573. ```powershell
  574. $PROBE_PRINCIPAL = '<probePrincipalId>'
  575. (Get-Content infra\probe-role-assignment.json -Raw).Replace('<PROBE_PRINCIPAL_ID>', $PROBE_PRINCIPAL).
  576. Replace('<API_SERVICE_PRINCIPAL_ID>', $API_SP) | Set-Content "$env:TEMP\probe-role.json" -Encoding utf8
  577. az rest --method POST --headers Content-Type=application/json `
  578. --url "https://graph.microsoft.com/v1.0/servicePrincipals/$PROBE_PRINCIPAL/appRoleAssignments" `
  579. --body "@$env:TEMP\probe-role.json"
  580. ```
  581. **2A.5 Aplicación y job de prueba.** [tools/deploy-mcp-app.ps1](./tools/deploy-mcp-app.ps1) toma las
  582. salidas de la infraestructura base y despliega [infra/app.bicep](./infra/app.bicep). Por ahora, solo
  583. se permite como origen la subred de ACA y no hay clientes delegados:
  584. ```powershell
  585. .\tools\deploy-mcp-app.ps1 -AllowedSourceCidrs '10.91.0.0/23' -AllowedClientIds @()
  586. ```
  587. **2A.6 Verificación** desde la red privada, con un token real de Entra (modo de aplicación):
  588. ```powershell
  589. az containerapp job start -n mcp-server-probe -g $RG
  590. az containerapp job execution list -n mcp-server-probe -g $RG -o table # Status: Succeeded
  591. ```
  592. El job comprueba que el DNS resuelve a una IP privada, que las peticiones sin token reciben 401 y
  593. que `initialize`, `tools/list` y `tools/call` funcionan.
  594. #### 2B. [MCP externo] Preparar un MCP existente (GCP, on-premises u otra red)
  595. Con los datos de la [sección 3.1](#31-datos-necesarios-del-servidor-mcp), el equipo propietario del
  596. MCP debe dejar preparado lo siguiente:
  597. | # | Acción en el lado del MCP | Cómo verificarlo |
  598. |---|---|---|
  599. | 1 | Exponer el MCP en **Streamable HTTP** (`POST` en la ruta MCP) | Una petición `POST` sin token devuelve **401**, no 404 ni 405 |
  600. | 2 | Presentar un **certificado de CA pública** con la cadena completa y el FQDN en el SAN ([2.6](#26-certificado-tls-del-mcp-qué-es-una-ca-y-qué-exige-power-platform)) | Comando de PowerShell de la sección 2.6 desde la red interna: la raíz debe ser una CA pública |
  601. | 3 | Publicar el FQDN en el **DNS privado** (Cloud DNS o corporativo), resolviendo a la IP privada | `nslookup <fqdn> <dns>` desde la red interna |
  602. | 4 | Implementar el **contrato de validación del token** de Entra (tabla de la sección 3.1), con el appId de la API (Paso 1) y el cliente del conector (Paso 5) | Un token de otra aplicación o sin el rol `MCP.User` recibe 403 |
  603. | 5 | Permitir la **salida HTTPS** del MCP hacia `login.microsoftonline.com` para descargar las claves JWKS | Validación de un token real (Paso 6.5) |
  604. | 6 | Preparar la regla de firewall que **admitirá TCP 443 desde las dos subredes delegadas** de Power Platform (sus rangos se definen en el Paso 4) | Diagnóstico del Paso 4.5 |
  605. | 7 | Registrar cada llamada con un identificador de petición y la identidad (`oid`), **sin tokens** | Correlación en las pruebas (sección 5) |
  606. > Si el MCP no puede validar tokens de Entra, valora un **front APIM interno** en Azure que haga
  607. > `validate-jwt` y reenvíe al MCP (ver [2.2](#22-arquitectura-de-referencia-mcp-en-google-cloud-u-on-premises)).
  608. > Con otro proveedor OAuth, sus URL de autorización y token deben ser accesibles públicamente.
  609. #### 2C. [Laboratorio GCP] MCP en Google Cloud dentro de una VPC, a través de VPN (validado)
  610. Reproduce de extremo a extremo el escenario de referencia: el MCP está **en Google Cloud**, sin acceso
  611. desde Internet, y Power Platform llega a él por las subredes delegadas, el VPN Gateway de Azure y un
  612. túnel IPsec hasta la VPC de GCP. Se usa **la misma imagen** que en 2A, y se prueba con un **agente
  613. nuevo** de Copilot Studio, sin tocar el existente.
  614. **Por qué Cloud Run con acceso interno y Private Service Connect**
  615. - Cloud Run con `ingress=internal` **rechaza las peticiones de Internet** (responde 404) y acepta las
  616. que llegan **desde redes conectadas por Cloud VPN**, que Google considera internas
  617. ([documentación](https://cloud.google.com/run/docs/securing/ingress)).
  618. - Desde la red privada se llega a la URL `*.run.app` a través de un **endpoint Private Service
  619. Connect (PSC) para APIs de Google**: una IP privada de la VPC que se anuncia a Azure por BGP. En
  620. Azure, el nombre del servicio se resuelve a esa IP con una zona DNS privada
  621. ([patrón documentado](https://cloud.google.com/run/docs/securing/private-networking)).
  622. - La URL `*.run.app` presenta un certificado de **Google Trust Services**, una CA pública: cumple el
  623. requisito de la [sección 2.6](#26-certificado-tls-del-mcp-qué-es-una-ca-y-qué-exige-power-platform)
  624. **sin necesitar un dominio propio**.
  625. ```mermaid
  626. flowchart LR
  627. subgraph M365["Microsoft 365 / Power Platform"]
  628. T["Teams / Probar"] --> A["Agente nuevo<br/>Asistente MCP GCP VNet"]
  629. A --> C["Conector MCP<br/>MCP GCP privado<br/>OAuth delegado Entra"]
  630. end
  631. C -. "OAuth/token" .-> E["Microsoft Entra ID"]
  632. subgraph AZ["Azure · rg-mcp-lab"]
  633. S1["Subredes delegadas PP<br/>10.92.0.0/26 · 10.93.0.0/26<br/>useRemoteGateways"]
  634. HUB["mcp-lab-vnet (hub)<br/>VPN Gateway VpnGw1AZ · ASN 65515<br/>IP pública"]
  635. DNSZ["DNS privado<br/>host exacto …run.app<br/>→ 10.96.0.10"]
  636. end
  637. C -->|"Subnet injection"| S1
  638. S1 -->|"peering + gateway transit"| HUB
  639. S1 -.-> DNSZ
  640. HUB <-->|"HA VPN · 2 túneles IPsec + BGP<br/>169.254.21.0/30 · 169.254.22.0/30"| GW
  641. subgraph GCP["Google Cloud · europe-west1"]
  642. GW["HA VPN + Cloud Router<br/>ASN 64514<br/>anuncia 10.95.0.0/24 y 10.96.0.10/32"]
  643. PSC["Endpoint PSC APIs de Google<br/>10.96.0.10"]
  644. CR["Cloud Run mcp-server-gcp<br/>ingress = internal<br/>imagen mcp-server:v5"]
  645. GW --> PSC --> CR
  646. end
  647. CR -. "JWKS (salida HTTPS)" .-> E
  648. ```
  649. **Valores del laboratorio**
  650. | Elemento | Valor |
  651. |---|---|
  652. | Proyecto GCP | `<GCP_PROJECT_ID>` (número `<GCP_PROJECT_NUMBER>`), región `europe-west1` |
  653. | VPC / subred | `mcp-lab-vpc` / `mcp-lab-subnet` `10.95.0.0/24` (Private Google Access) |
  654. | Endpoint PSC | `mcplabpsc`, IP `10.96.0.10`, paquete `all-apis` |
  655. | HA VPN / Cloud Router | `mcp-lab-havpn` (`<GCP_HAVPN_IP_0>`, `<GCP_HAVPN_IP_1>`) / `mcp-lab-router`, ASN `64514` |
  656. | Túneles y BGP | `mcp-lab-tunnel0`: GCP `169.254.21.2` ↔ Azure `169.254.21.1` · `mcp-lab-tunnel1`: GCP `169.254.22.2` ↔ Azure `169.254.22.1` |
  657. | VPN Gateway de Azure | `mcp-lab-vpngw` (VpnGw1AZ, activo-pasivo), IP `<AZURE_VPNGW_IP>`, ASN `65515`, en `GatewaySubnet` `10.91.255.0/27` |
  658. | MCP en Cloud Run | `mcp-server-gcp`, URL `https://<CLOUD_RUN_HOST>/mcp`, imagen `europe-west1-docker.pkg.dev/<GCP_PROJECT_ID>/mcp-lab/mcp-server:v5` |
  659. | Variables del MCP | `TENANT_ID`, `API_CLIENT_ID`, `ALLOWED_CLIENT_IDS=<CONNECTOR_APP_ID>`, `PROBE_CLIENT_ID=<PROBE_CLIENT_ID>`, `RESOURCE_URL`, `MCP_RUNTIME=gcp-cloud-run-europe-west1` |
  660. **2C.1 Acceso y permisos en GCP**
  661. ```powershell
  662. gcloud auth login <tu-cuenta-gcp> # interactivo
  663. gcloud config set project $cfg.gcp.projectId
  664. ```
  665. La cuenta necesita, además de Cloud Run y Artifact Registry, `roles/compute.networkAdmin`,
  666. `roles/servicedirectory.editor` y `roles/dns.admin`; los dos últimos los usa el endpoint PSC. En el
  667. laboratorio se asignaron así, con autorización del responsable:
  668. ```powershell
  669. foreach ($r in 'roles/compute.networkAdmin','roles/servicedirectory.editor','roles/dns.admin') {
  670. gcloud projects add-iam-policy-binding $cfg.gcp.projectId --member='user:<tu-cuenta-gcp>' --role=$r --condition=None
  671. }
  672. gcloud services enable servicedirectory.googleapis.com dns.googleapis.com --project $cfg.gcp.projectId
  673. ```
  674. **2C.2 VPN Gateway de Azure (lanzarlo primero: tarda entre 30 y 45 min).** Se añade la
  675. `GatewaySubnet` con un comando puntual, porque redesplegar `main.bicep` en un laboratorio existente
  676. reescribiría la VNet (ver [6.7](#67-mcp-en-gcp-a-través-de-vpn-laboratorio)):
  677. ```powershell
  678. $P = $cfg.azure.namePrefix; $G = $cfg.gcp.prefix
  679. az network vnet subnet create -g $RG --vnet-name "$P-vnet" -n GatewaySubnet --address-prefixes 10.91.255.0/27
  680. az deployment group create -g $RG -n vpn-gateway --template-file infra\vpn-gateway.bicep `
  681. --parameters vnetName="$P-vnet" gatewayName="$P-vpngw" --query properties.outputs.publicIp.value -o tsv
  682. # guarda la IP en gcp.azureVpnGatewayIp
  683. ```
  684. **2C.3 Red de GCP**, mientras se crea el gateway.
  685. [infra/gcp/setup-gcp-network.ps1](./infra/gcp/setup-gcp-network.ps1) es idempotente y crea:
  686. - la VPC y la subred;
  687. - el endpoint PSC;
  688. - HA VPN y Cloud Router, que anuncia la subred y la IP del PSC;
  689. - el gateway externo con la IP de Azure;
  690. - los dos túneles con sus sesiones BGP.
  691. La clave IPsec se genera aleatoriamente y se guarda **cifrada con DPAPI** (solo tu usuario de Windows
  692. puede leerla) en `gcp.pskFile` (por defecto `%LOCALAPPDATA%\mcp-lab\vpn-psk.clixml`). Nunca se muestra ni se guarda en el repositorio.
  693. ```powershell
  694. .\infra\gcp\setup-gcp-network.ps1 # lee gcp.* de config/lab.config.json; muestra las IP de HA VPN
  695. ```
  696. **2C.4 Conexiones de Azure hacia las dos interfaces de HA VPN** (cuando el gateway está listo). La
  697. clave se lee del fichero cifrado y se pasa como parámetro seguro; el fichero temporal de
  698. parámetros se borra al terminar:
  699. ```powershell
  700. $psk = [Net.NetworkCredential]::new('', (Import-Clixml ([Environment]::ExpandEnvironmentVariables($cfg.gcp.pskFile)))).Password
  701. $pf = Join-Path $env:TEMP ([guid]::NewGuid().ToString() + '.json')
  702. @{ '$schema'='https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#'; contentVersion='1.0.0.0'
  703. parameters=@{ gatewayName=@{ value="$P-vpngw" }; prefix=@{ value="$P-gcp" }; gcpInterfaceIps=@{ value=@('<GCP_HAVPN_IP_0>','<GCP_HAVPN_IP_1>') # salida haVpnInterfaceIps de 2C.3 }; sharedKey=@{ value=$psk } } } |
  704. ConvertTo-Json -Depth 5 | Set-Content $pf
  705. try { az deployment group create -g $RG -n vpn-gcp-connections --template-file infra\vpn-gcp-connections.bicep --parameters "@$pf" }
  706. finally { Remove-Item $pf -Force; Remove-Variable psk }
  707. ```
  708. **2C.5 Comprobar túneles y BGP**
  709. ```powershell
  710. gcloud compute vpn-tunnels list --filter="name~$G" --format='table(name,status,detailedStatus)' # ESTABLISHED
  711. gcloud compute routers get-status "$G-router" --region europe-west1 --format='value(result.bgpPeerStatus[].status)' # UP;UP
  712. az network vnet-gateway list-learned-routes -g $RG -n "$P-vpngw" --query "value[?origin=='EBgp'].network" -o tsv # 10.95.0.0/24, 10.96.0.10/32
  713. ```
  714. **2C.6 Imagen y despliegue en Cloud Run.** La imagen se construye en ACR y se copia a Artifact
  715. Registry con [crane](https://github.com/google/go-containerregistry), así que no hacen falta Docker
  716. local ni Cloud Build. Las credenciales temporales se guardan en una carpeta temporal que se borra al
  717. terminar:
  718. ```powershell
  719. $IMG = "$($cfg.mcp.imageName):$($cfg.mcp.imageTag)"
  720. $AR = "europe-west1-docker.pkg.dev/$($cfg.gcp.projectId)/mcp-lab"
  721. az acr build --registry $cfg.azure.acrName --image $IMG --file Dockerfile . --no-logs
  722. gcloud artifacts repositories create mcp-lab --repository-format=docker --location=europe-west1
  723. $env:DOCKER_CONFIG = Join-Path $env:TEMP ([guid]::NewGuid())
  724. az acr login -n $cfg.azure.acrName --expose-token --query accessToken -o tsv |
  725. crane auth login "$($cfg.azure.acrName).azurecr.io" -u 00000000-0000-0000-0000-000000000000 --password-stdin
  726. gcloud auth print-access-token | crane auth login europe-west1-docker.pkg.dev -u oauth2accesstoken --password-stdin
  727. crane copy "$($cfg.azure.acrName).azurecr.io/$IMG" "$AR/$IMG"
  728. Remove-Item -Recurse -Force $env:DOCKER_CONFIG
  729. $url = "https://$($cfg.gcp.cloudRunHost)"
  730. gcloud run deploy $cfg.gcp.cloudRunService --region europe-west1 `
  731. --image "$AR/$IMG" `
  732. --ingress internal --no-invoker-iam-check --min-instances 0 --max-instances 2 --memory 512Mi `
  733. --set-env-vars "TENANT_ID=$TENANT,API_CLIENT_ID=$API_APP,ALLOWED_CLIENT_IDS=$($cfg.entra.connectorClientId),PROBE_CLIENT_ID=$($cfg.azure.probeClientId),RESOURCE_URL=$url,MCP_RUNTIME=gcp-cloud-run-europe-west1" `
  734. --labels 'purpose=mcp-oauth-private-poc,data=synthetic-only'
  735. ```
  736. `--no-invoker-iam-check` desactiva la comprobación de IAM de Google en Cloud Run: la identidad la
  737. valida el propio MCP con el token de Entra. Lo que impide llegar desde Internet es `--ingress internal`.
  738. > `gcp.cloudRunHost` se conoce antes de desplegar: Cloud Run usa
  739. > `<servicio>-<número de proyecto>.<región>.run.app`. El número del proyecto se obtiene con
  740. > `gcloud projects describe $cfg.gcp.projectId --format='value(projectNumber)'`. Compruébalo después
  741. > con `gcloud run services describe $cfg.gcp.cloudRunService --region europe-west1 --format='value(status.url)'`.
  742. **2C.7 DNS privado en Azure** solo para el nombre del servicio (no afecta a otros `*.run.app`),
  743. enlazado a la VNet hub y a las dos VNets de Power Platform
  744. ([infra/gcp-mcp-dns.bicep](./infra/gcp-mcp-dns.bicep)):
  745. ```powershell
  746. $p = $cfg.azure.namePrefix
  747. $ids = @("$p-vnet") + ($cfg.powerPlatform.regions | ForEach-Object { "$p-pp-$_" }) |
  748. ForEach-Object { "/subscriptions/$($cfg.subscriptionId)/resourceGroups/$RG/providers/Microsoft.Network/virtualNetworks/$_" }
  749. $pf = Join-Path $env:TEMP 'gcp-mcp-dns.parameters.json'
  750. @{ '$schema'='https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#'; contentVersion='1.0.0.0'
  751. parameters=@{ hostName=@{ value=$cfg.gcp.cloudRunHost }; pscAddress=@{ value=$cfg.gcp.pscAddress }; vnetIds=@{ value=@($ids) } } } |
  752. ConvertTo-Json -Depth 5 | Set-Content $pf
  753. az deployment group create -g $RG -n gcp-mcp-dns --template-file infra\gcp-mcp-dns.bicep --parameters "@$pf"
  754. Remove-Item $pf
  755. ```
  756. **2C.8 Power Platform usa el gateway del hub (gateway transit).** Con la política **ya vinculada**, se
  757. redespliega la red con `useRemoteGateways=true` y `manageEnterprisePolicy=false`. Copia
  758. [infra/pp-network.lab.example.parameters.json](./infra/pp-network.lab.example.parameters.json) como
  759. `infra/pp-network.lab.parameters.json` (ignorado por git) y sustituye los marcadores; los NSG de
  760. `subnetNsgIds` son los que Azure asocia a las subredes delegadas (consúltalos con
  761. `az network vnet subnet show`). Una política vinculada no se puede modificar:
  762. ```powershell
  763. az deployment group create -g $RG -n pp-network-gateway-transit --template-file infra\pp-network.bicep `
  764. --parameters '@infra\pp-network.lab.parameters.json'
  765. gcloud compute routers get-status "$($cfg.gcp.prefix)-router" --region europe-west1 --format='value(result.bestRoutes[].destRange)'
  766. # Debe incluir 10.92.0.0/24 y 10.93.0.0/24 (subredes de Power Platform)
  767. ```
  768. Después del cambio, los diagnósticos de Power Platform pueden devolver **503 durante unos
  769. minutos** mientras se reinicializa la red.
  770. **2C.9 Pruebas de red**
  771. ```powershell
  772. # a) Desde Azure: el job de prueba, redirigido al MCP de GCP
  773. az containerapp job start -n "$($cfg.mcp.appName)-probe" -g $RG `
  774. --image "$($cfg.azure.acrName).azurecr.io/$($cfg.mcp.imageName):$($cfg.mcp.imageTag)" --container-name probe `
  775. --command node --args src/probe.mjs `
  776. --env-vars "MCP_URL=$url/mcp" "API_RESOURCE=api://$API_APP" "PROBE_CLIENT_ID=$($cfg.azure.probeClientId)"
  777. # b) Desde Power Platform, en las dos regiones
  778. .\tools\pp-vnet-diagnostics.ps1 -HostName $cfg.gcp.cloudRunHost
  779. # c) Desde Internet: debe fallar (404)
  780. curl.exe -s -o NUL -w '%{http_code}' "$url/healthz"
  781. # Auditoría de llamadas en Cloud Run
  782. .\tools\show-gcp-mcp-audit.ps1 -Minutes 60
  783. ```
  784. **2C.10 Agente nuevo en Copilot Studio.** Sigue los Pasos 6 y 7 con estas diferencias:
  785. | Campo | Valor |
  786. |---|---|
  787. | Nombre del agente | `Asistente MCP GCP VNet`, con las mismas instrucciones del Paso 6.1 |
  788. | Server name | `MCP GCP privado`. Con un nombre distinto se crea un **conector nuevo** |
  789. | Server URL | `https://<CLOUD_RUN_HOST>/mcp` |
  790. | Client ID, URL de OAuth y scopes | Los mismos del Paso 6.2 (misma aplicación cliente y misma API) |
  791. | Client secret | Uno nuevo con `.\tools\new-connector-secret.ps1` |
  792. | Callback URL | Registrarla con `.\tools\set-connector-redirect.ps1` y **esperar 1-2 minutos** antes de conectar (si no, aparece `AADSTS50011`) |
  793. Respuesta esperada en **Probar** y en Teams: `"runtime": "gcp-cloud-run-europe-west1"`, `"mode": "delegated"` y
  794. el `objectId` del usuario. Para que otros usuarios usen este agente, aplica el Paso 8 con el nuevo
  795. conector: `.\tools\grant-connector-access.ps1 -ConnectorDisplayName 'MCP GCP privado'` (aplicado en
  796. el laboratorio el 20/11), comparte el agente con ellos y usa su enlace de instalación (Paso 7).
  797. ### Paso 3. Entorno Power Platform
  798. **3.1 Comprueba la ubicación antes de crear el entorno.** El tenant puede asignar la ubicación
  799. concreta dentro de una *macrorregión*. Esa ubicación tiene que estar en la tabla de VNet Support, y
  800. tu suscripción debe poder crear redes en sus dos regiones.
  801. ```powershell
  802. pac environment-management get-supported-locations --json # locationSelectionMode y macroRegions
  803. ```
  804. **3.2 Crear el entorno** restringido al grupo piloto y activar Managed Environment:
  805. ```powershell
  806. pac admin create --name 'MCP Private Lab' --type Production --macro-region north-america `
  807. --currency EUR --language 3082 --domain mcp-private-lab --security-group-id $GROUP
  808. # guarda el id del entorno en powerPlatform.environmentId y su URL (https://<org>.crm….dynamics.com)
  809. # en powerPlatform.orgUrl; recarga las variables (Paso 0)
  810. pac environment-management get-environment-by-id-for-user --environment $ENV_ID --json # anota azureRegion
  811. pac admin set-governance-config --environment $ENV_ID --protection-level Standard
  812. ```
  813. En el laboratorio, `azureRegion` = `canadacentral`, así que la pareja es **Canada Central + Canada East**.
  814. ### Paso 4. VNet Support y conectividad con el MCP
  815. **4.1 Planificar las redes.** Necesitas dos rangos (uno por región de la pareja) que **no se solapen**
  816. con Azure, GCP ni on-premises. Cada subred delegada debe tener el mismo tamaño; el laboratorio usa
  817. `/26`. Consulta la [guía de dimensionamiento](https://learn.microsoft.com/en-us/power-platform/admin/vnet-support-overview#estimating-subnet-size-for-power-platform-environments).
  818. > **El DNS de estas VNets debe quedar definitivo antes del Paso 4.4**: con la política vinculada no
  819. > se puede cambiar sin desvincularla antes.
  820. **4.2 Redes delegadas, conectividad y Enterprise Policy.** [infra/pp-network.bicep](./infra/pp-network.bicep)
  821. crea una VNet por región con una subred delegada a `Microsoft.PowerPlatform/enterprisePolicies` y la
  822. política `NetworkInjection`. La conexión con el MCP se configura con parámetros:
  823. | Parámetro | [Laboratorio] MCP en ACA | [MCP externo] GCP / on-premises |
  824. |---|---|---|
  825. | `policyLocation`, `primaryRegion`, `secondaryRegion` | `canada`, `canadacentral`, `canadaeast` | Según el entorno; p. ej. `europe`, `westeurope`, `northeurope` |
  826. | `backendVnetId` | VNet del MCP en ACA | VNet **hub** con VPN Gateway o ExpressRoute |
  827. | `useRemoteGateways` | `false` | `true` (*gateway transit*: las subredes usan la VPN/ER del hub) |
  828. | `allowForwardedTraffic` | `false` | `true` si hay un firewall o NVA en el hub |
  829. | `privateDnsZoneId` | Zona privada de ACA | Vacío (o una zona privada de Azure si el MCP la usa) |
  830. | `dnsServers` | Vacío (Azure DNS) | IP del *inbound endpoint* del Private Resolver o DNS corporativo |
  831. | `createReversePeering` | `true` | `true` si tienes permisos en el hub; si no, el equipo de red crea el peering `to-pp-<región>` con *Allow gateway transit* |
  832. | `subnetNsgIds` | NSG existentes en las subredes | NSG opcionales para filtrar la salida |
  833. | `manageEnterprisePolicy` | `true` al crear; **`false` una vez vinculada** | Igual. Una política vinculada no se puede modificar (`EnterprisePolicyUpdateNotAllowed`) |
  834. ```powershell
  835. # [Laboratorio]: copia infra\pp-network.lab.example.parameters.json como infra\pp-network.lab.parameters.json
  836. # (ignorado por git) y sustituye los marcadores. En el primer despliegue usa manageEnterprisePolicy=true,
  837. # useRemoteGateways=false (true solo con la opción 2C) y subnetNsgIds=[]
  838. az deployment group create -g $RG -n pp-network --template-file infra\pp-network.bicep `
  839. --parameters '@infra\pp-network.lab.parameters.json'
  840. # [MCP externo]: copia y completa infra\pp-network.hub.example.parameters.json
  841. az deployment group create -g <rg-red-pp> -n pp-network --template-file infra\pp-network.bicep `
  842. --parameters '@infra\pp-network.<entorno>.parameters.json'
  843. ```
  844. Anota la salida `policySystemId` y guarda en `powerPlatform.regions` y
  845. `powerPlatform.delegatedSubnetCidrs` la pareja de regiones y las subredes delegadas (salida
  846. `ppSubnetPrefixes`).
  847. **4.3 [MCP externo] Conectividad, DNS y firewall.** Lo configura el equipo de red de Azure junto con
  848. el equipo de GCP u on-premises, usando los datos de la [sección 3.1](#31-datos-necesarios-del-servidor-mcp):
  849. | Elemento | Qué hay que configurar | Comprobación |
  850. |---|---|---|
  851. | Interconexión | VPN HA hacia GCP (Cloud VPN + Cloud Router, BGP) o Cross-Cloud Interconnect; VPN site-to-site o ExpressRoute hacia on-premises. Termina en el VPN o ExpressRoute Gateway del hub | Túneles conectados y sesión BGP establecida |
  852. | Rutas | Anunciar **los dos rangos de las subredes delegadas** hacia GCP u on-premises y recibir el rango del MCP. Con *gateway transit*, el hub los propaga a las VNets de Power Platform | Rutas efectivas en el hub; rutas aprendidas en Cloud Router o en el router on-premises |
  853. | DNS | Azure DNS Private Resolver con una regla de reenvío para la zona del MCP hacia el *inbound forwarder* de Cloud DNS o el DNS corporativo. Las VNets de Power Platform usan la IP del *inbound endpoint* del resolver (`dnsServers`) | Paso 4.5: el DNS devuelve la IP privada |
  854. | Firewall del MCP | Permitir TCP 443 **desde los dos rangos delegados** hacia la VIP del MCP (reglas de firewall VPC en GCP, firewall corporativo o F5) | Paso 4.5: TCP correcto |
  855. | NAT | Evitarlo. Si existe, la lista de orígenes permitidos debe usar las IP traducidas | — |
  856. **4.4 Vincular la política al entorno.** Es la misma API que usa el cmdlet oficial
  857. `Enable-SubnetInjection`. Usa el `policySystemId` del Paso 4.2:
  858. ```powershell
  859. $POLICY_SYSTEM_ID = '<policySystemId>' # p. ej. /regions/canada/providers/Microsoft.PowerPlatform/enterprisePolicies/<guid>
  860. @{ SystemId = $POLICY_SYSTEM_ID } | ConvertTo-Json | Set-Content "$env:TEMP\link.json" -Encoding ascii
  861. az rest --method POST --resource https://service.powerapps.com/ --headers Content-Type=application/json `
  862. --url "https://api.bap.microsoft.com/providers/Microsoft.BusinessAppPlatform/environments/$ENV_ID/enterprisePolicies/NetworkInjection/link?api-version=2019-10-01" `
  863. --body "@$env:TEMP\link.json"
  864. # Comprobación: debe devolver "Linked"
  865. az rest --method GET --resource https://service.powerapps.com/ `
  866. --url "https://api.bap.microsoft.com/providers/Microsoft.BusinessAppPlatform/scopes/admin/environments/${ENV_ID}?api-version=2016-11-01" `
  867. --query properties.enterprisePolicies.vNets.linkStatus -o tsv
  868. ```
  869. > La vinculación puede causar hasta **30 minutos** de inestabilidad mientras se inicializa la red.
  870. **4.5 Diagnóstico desde dentro de Power Platform.** El script ejecuta las comprobaciones de DNS,
  871. TCP y TLS en un contenedor del entorno, en **cada** región. Funciona igual con el MCP del
  872. laboratorio y con un MCP externo; solo cambia `-HostName`. El entorno y las regiones se leen de
  873. `powerPlatform.environmentId` y `powerPlatform.regions` (o se pasan con `-EnvironmentId` y `-Regions`):
  874. ```powershell
  875. # [Laboratorio]
  876. .\tools\pp-vnet-diagnostics.ps1 -HostName $MCP_HOST
  877. # [MCP externo]: FQDN del dato 1 de la sección 3.1
  878. .\tools\pp-vnet-diagnostics.ps1 -HostName mcp.example.internal -OutFile "$env:TEMP\pp-diagnostics.json"
  879. ```
  880. Resultado esperado **en las dos regiones**:
  881. | Comprobación | Correcto | Si falla |
  882. |---|---|---|
  883. | DNS | Devuelve la IP privada del MCP | DNS de la VNet, reglas del Private Resolver, zona enlazada |
  884. | TCP 443 | `tcpSuccess: true` | Peering o *gateway transit*, rutas BGP, firewall del MCP |
  885. | TLS | Certificado no autofirmado ni caducado; `sslErrors: None` | Certificado de CA privada, cadena incompleta o SAN distinto del FQDN |
  886. | (cualquiera) **503** | — | La red aún se está inicializando; espera y repite |
  887. **4.6 [Laboratorio] Permitir las subredes de Power Platform en el MCP de ACA:**
  888. ```powershell
  889. .\tools\deploy-mcp-app.ps1 -AllowedClientIds @() # orígenes: azure.acaSubnetCidr + powerPlatform.delegatedSubnetCidrs
  890. ```
  891. En un MCP externo, este control es la regla de firewall del Paso 4.3.
  892. ### Paso 5. Aplicación cliente OAuth del conector
  893. ```powershell
  894. (Get-Content infra\connector-client-registration.json -Raw).Replace('<API_APP_ID>', $API_APP) |
  895. Set-Content "$env:TEMP\connector-client.json" -Encoding utf8
  896. az rest --method POST --headers Content-Type=application/json `
  897. --url https://graph.microsoft.com/v1.0/applications --body "@$env:TEMP\connector-client.json" --query appId -o tsv
  898. # guarda el appId en entra.connectorClientId
  899. az ad sp create --id <clientAppId> --query id -o tsv # = <clientSpId>
  900. ```
  901. Concede consentimiento de administrador **solo** para `MCP.Access`, para que los usuarios no vean
  902. una pantalla de consentimiento:
  903. ```powershell
  904. @{ clientId = '<clientSpId>'; consentType = 'AllPrincipals'; resourceId = $API_SP; scope = 'MCP.Access' } |
  905. ConvertTo-Json | Set-Content "$env:TEMP\grant.json" -Encoding ascii
  906. az rest --method POST --headers Content-Type=application/json `
  907. --url https://graph.microsoft.com/v1.0/oauth2PermissionGrants --body "@$env:TEMP\grant.json"
  908. ```
  909. Autoriza ese cliente en el MCP:
  910. ```powershell
  911. # [Laboratorio]: el script usa entra.connectorClientId y las subredes de config/lab.config.json
  912. .\tools\deploy-mcp-app.ps1
  913. ```
  914. **[MCP externo]:** entrega al equipo del MCP el **client ID** de esta aplicación, para que lo añada
  915. a la lista de clientes permitidos (`azp`), junto con el tenant y el appId de la API (contrato de la
  916. sección 3.1).
  917. ### Paso 6. Agente y herramienta MCP en Copilot Studio
  918. **6.1 Crear el agente** en [copilotstudio.microsoft.com](https://copilotstudio.microsoft.com), en el
  919. entorno **MCP Private Lab**:
  920. - **Crear → Nuevo agente → Omitir para configurar**. Nombre: `Asistente MCP Azure VNet`.
  921. - **Instrucciones**, idénticas en todos los agentes para que las respuestas tengan siempre el mismo
  922. formato. Sin ellas, el modelo varía la presentación entre JSON, tablas y listas:
  923. ```
  924. Cuando el usuario pida comprobar la conexión con el MCP, usa la herramienta iam_connection_check y responde siempre en español con este formato exacto, sin añadir, quitar ni reordenar secciones:
  925. 1. Primera línea: "La conexión con el MCP funciona: el servidor MCP privado está accesible y el token se ha validado."
  926. 2. Línea con el texto en negrita: **Resultado completo:**
  927. 3. Un bloque de código json con la respuesta de la herramienta tal cual, sin modificar, resumir ni reordenar campos. Nunca uses tablas ni listas para mostrar este resultado.
  928. 4. Una lista con exactamente estos cuatro puntos, en este orden:
  929. - **Origen:** el valor del campo runtime, explicando si el servidor MCP se ejecuta en Azure o en Google Cloud.
  930. - **Estado:** el token es válido y hay acceso.
  931. - **Modo:** el valor de identity.mode; si es delegated, indica que se usan permisos delegados en nombre de tu usuario.
  932. - **Datos sintéticos:** synthetic: true indica que la respuesta usa datos de prueba y no sistemas corporativos reales.
  933. Si la herramienta devuelve un error, no uses este formato: explica el error en una o dos frases e indica el código HTTP si aparece.
  934. ```
  935. El campo `runtime` lo devuelve el MCP según su variable `MCP_RUNTIME`:
  936. `azure-container-apps-northeurope` en ACA y `gcp-cloud-run-europe-west1` en Cloud Run.
  937. - **Configuración → Seguridad → Autenticación:** deja **Authenticate with Microsoft** (valor
  938. predeterminado). Proporciona SSO en el chat 1:1 de Teams sin más configuración.
  939. **6.2 Añadir el servidor MCP:** **Herramientas → Agregar una herramienta → Nueva herramienta →
  940. Model Context Protocol**.
  941. | Campo | Valor |
  942. |---|---|
  943. | Server name | `MCP Private Lab` |
  944. | Server description | `Herramienta de diagnóstico del MCP privado. Úsala cuando el usuario pida comprobar la conexión con el MCP o verificar con qué identidad accede.` |
  945. | Server URL | [Laboratorio] `https://<MCP_HOST>/mcp` · [MCP externo] URL del dato 1 de la sección 3.1 |
  946. | Authentication | **OAuth 2.0** |
  947. | Type | **Manual** (Entra ID no admite registro dinámico de clientes) |
  948. | Client ID | `<CONNECTOR_APP_ID>` |
  949. | Client secret | Ejecuta `.\tools\new-connector-secret.ps1` y pega con **Ctrl+V** (no se muestra en pantalla; caduca en 30 días) |
  950. | Authorization URL | `https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize` |
  951. | Token URL template | `https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token` |
  952. | Refresh URL | La misma que Token URL |
  953. | Scopes | `api://<API_APP_ID>/MCP.Access offline_access` |
  954. Los marcadores corresponden a campos de `config/lab.config.json`: `<CONNECTOR_APP_ID>` =
  955. `entra.connectorClientId`, `<TENANT_ID>` = `tenantId`, `<API_APP_ID>` = `entra.apiClientId` y
  956. `<MCP_HOST>` = `mcp.host`. El *Server name* pasa a ser el nombre del conector: guárdalo en
  957. `powerPlatform.connectorDisplayName` (lo usa el Paso 8).
  958. **6.3 Registrar la callback URL.** Al pulsar **Create**, el asistente muestra una *callback URL*.
  959. Regístrala y limpia el portapapeles **en dos líneas separadas**:
  960. ```powershell
  961. .\tools\set-connector-redirect.ps1 -CallbackUrl 'https://global.consent.azure-apim.net/redirect/...'
  962. Set-Clipboard -Value ' '
  963. ```
  964. **6.4 Conexión y modo de credenciales:**
  965. 1. **Siguiente → Crear una nueva conexión → Iniciar sesión** con tu cuenta.
  966. 2. En **Editar herramienta**, deja **Autenticación = Cuenta de usuario final**: cada usuario inicia
  967. sesión con su propia cuenta. Comprueba que `iam_connection_check` aparece activada.
  968. 3. Pulsa **Listo**.
  969. **6.5 Probar** en **Probar**:
  970. - **[Laboratorio]** Escribe `Comprueba la conexión con el MCP`. La respuesta debe mostrar
  971. `mode: delegated`, tu `objectId` y `clientId: <CONNECTOR_APP_ID>`.
  972. - **[MCP externo]** Pide algo que use una de sus herramientas. En el registro del MCP debe aparecer
  973. la llamada con **tu `oid`** y con el `azp` del cliente del conector.
  974. ### Paso 7. Publicar en Teams
  975. 1. Pulsa **Publicar**.
  976. 2. En **Canales → Microsoft 365 y Microsoft Teams**:
  977. - **Disponibilidad:** *Microsoft 365 Copilot y Microsoft Teams* o *Solo en Microsoft Teams*.
  978. **No se puede cambiar después de publicar.**
  979. - **No uses** *Enviar al catálogo de la organización*: lo publicaría para toda la organización.
  980. - Pulsa **Guardar** y **vuelve a publicar**.
  981. 3. Ve a **Usar y compartir → Ver en Teams → Agregar → Abrir**. Si sale `AppDefinitionDoesntExist`
  982. (ocurre en la primera instalación de cada agente), publica de nuevo, espera unos 5 min y recarga
  983. Teams con Ctrl+F5.
  984. 4. Guarda el **enlace de instalación** para los demás usuarios. Todos los agentes de Copilot Studio
  985. comparten el identificador de app de Teams `<TEAMS_APP_ID>`: lo que identifica a **cada agente** es
  986. `templateInstanceId`. El enlace tiene esta forma:
  987. | Agente | Enlace de instalación |
  988. |---|---|
  989. | Asistente MCP Azure VNet | `https://teams.microsoft.com/l/app/<TEAMS_APP_ID>?templateInstanceId=<TEMPLATE_INSTANCE_ID_AZURE>&environment=<ENVIRONMENT_ID>` |
  990. | Asistente MCP GCP VNet (opción 2C) | `https://teams.microsoft.com/l/app/<TEAMS_APP_ID>?templateInstanceId=<TEMPLATE_INSTANCE_ID_GCP>&environment=<ENVIRONMENT_ID>` |
  991. **Al renombrar un agente:** revisa **Canales → Información acerca de**, publica, y cada usuario debe
  992. **desinstalar y volver a instalar** el agente en Teams para ver el nombre nuevo. Las conexiones se
  993. conservan y el enlace no cambia.
  994. ### Paso 8. Acceso de otros usuarios
  995. El creador del agente puede usarlo sin más. **Para cualquier otro usuario hay que cumplir los cinco
  996. requisitos siguientes**, que son independientes de la red y de OAuth:
  997. | # | Requisito | Cómo | Síntoma si falta |
  998. |---|---|---|---|
  999. | 1 | Pertenecer al **grupo piloto** | `az ad group member add` (Paso 1.3). Da acceso al entorno y el rol `MCP.User` | Sin acceso al entorno ni token del MCP |
  1000. | 2 | **Agente compartido** con el usuario | Copilot Studio → **…** → **Compartir** → usuario con permiso de *usuario* (no editor) | *«Su organización impidió la instalación de este agente»* |
  1001. | 3 | **Lectura del conector** | `.\tools\grant-connector-access.ps1` (una vez por grupo) | *«Connector information unavailable»* al crear la conexión |
  1002. | 4 | **Políticas del tenant** que permitan agentes de la organización | Centro de administración de M365 → Agentes → Configuración; Centro de administración de Teams → apps personalizadas | *«Su organización impidió la instalación…»* aunque el agente esté compartido |
  1003. | 5 | **Instalar el agente** | El usuario abre el enlace de instalación → **Agregar** → **Abrir** | — |
  1004. [tools/grant-connector-access.ps1](./tools/grant-connector-access.ps1) es idempotente y hace tres cosas:
  1005. - crea en Dataverse un **equipo vinculado al grupo de Entra**;
  1006. - le asigna el rol **Usuario Basic**;
  1007. - comparte **solo el conector del MCP** con permiso de lectura.
  1008. Así el acceso se gestiona con el grupo, no usuario a usuario.
  1009. **Primer uso de cada usuario:** el agente muestra una tarjeta **Conectar** y abre la página
  1010. *Administrar sus conexiones*. Allí el usuario pulsa **Conectar → Create new connection**, inicia
  1011. sesión con su cuenta y vuelve a Teams. Las siguientes veces se reutiliza su conexión.
  1012. ---
  1013. ## 5. Pruebas y resultados
  1014. ### 5.1 Cómo comprobar cada llamada
  1015. Cada respuesta de la herramienta de laboratorio incluye un `requestId`. Para ver en la auditoría quién llamó y con
  1016. qué resultado, espera entre 2 y 5 minutos (retraso de ingesta) y ejecuta:
  1017. ```powershell
  1018. .\tools\show-mcp-audit.ps1 -Minutes 30 # añade -OutFile <fichero>.json para guardar evidencia
  1019. ```
  1020. Cada sesión del agente genera un grupo de tres peticiones: `initialize` (200), `notifications/initialized`
  1021. (202) y `tools/list` o `tools/call` (200).
  1022. **[MCP externo]** `show-mcp-audit.ps1` solo lee la auditoría del MCP de laboratorio. Con un MCP
  1023. externo, usa su propio registro (dato 16 de la sección 3.1) y correlaciona por hora, `oid` y `azp`.
  1024. ### 5.2 Plan de pruebas
  1025. | # | Prueba | Cómo | Resultado esperado | Aplica a |
  1026. |---|---|---|---|---|
  1027. | L | Pruebas locales | `npm test` | 18/18 | Laboratorio |
  1028. | P | MCP privado con token real de aplicación | `az containerapp job start -n mcp-server-probe -g $RG` | `Succeeded` | Laboratorio |
  1029. | N | Restricción de origen | Cambiar temporalmente la regla de IP y lanzar el job | 403 en la entrada; ningún evento en el MCP | Laboratorio |
  1030. | D | Ruta Power Platform → MCP | `.\tools\pp-vnet-diagnostics.ps1 …` | DNS privado, TCP y TLS correctos en ambas regiones | Ambos |
  1031. | C1 | OAuth delegado desde Copilot Studio | Panel **Probar** | `delegated` con el `objectId` del usuario | Ambos |
  1032. | C2 | El tráfico pasa por las subredes delegadas | Laboratorio: `.\tools\toggle-pp-access.ps1 -Mode Block`. MCP externo: retirar temporalmente las subredes PP de la regla del firewall. Después, repetir C1 | La herramienta falla y **no llega nada al MCP** | Ambos |
  1033. | C3 | Restauración | Laboratorio: `.\tools\toggle-pp-access.ps1 -Mode Allow`. MCP externo: restaurar la regla. Después, repetir C1 | Vuelve a funcionar. **No dejar el bloqueo activo** | Ambos |
  1034. | E1 | Teams con el creador | Chat 1:1 | Sin inicio de sesión del agente (SSO); `delegated` | Ambos |
  1035. | E2 | Teams con un segundo usuario piloto | Enlace de instalación + primer uso | `delegated` con **su** `objectId` | Ambos |
  1036. | E3 | Usuario fuera del grupo piloto | Enlace de instalación | Rechazado; anotar en qué capa (2.5) | Ambos |
  1037. | E4 | Renovación del token | Repetir pasados más de 90 min | Funciona sin reconectar | Ambos |
  1038. | E5 | Revocación | Sacar al usuario del grupo y esperar a que caduque el token | Rechazado; después, volver a añadirlo | Ambos |
  1039. ### 5.3 Resultados obtenidos
  1040. | # | Resultado | Fecha (UTC) | Evidencia |
  1041. |---|---|---|---|
  1042. | L | ✅ 18/18 | 20/11 | `local-tests.txt` |
  1043. | P | ✅ `Succeeded` (versiones v1 a v4); DNS `10.91.1.235`; sin token → 401 | 19/11 y 20/11 | `probe-executions.json`, `law-probe-results.json` |
  1044. | N | ✅ 403 en la entrada; 0 eventos en el MCP | 19/11 19:49 | `law-probe-results.json` |
  1045. | D | ✅ Canada Central y Canada East: DNS → `10.91.1.235`, TCP 443, TLS 1.3 con certificado público válido | 19/11 | `pp-vnet-diagnostics.json` |
  1046. | C1 | ✅ `tools/call` `delegated`, admin, cliente `<CONNECTOR_APP_ID>`; requestId `3975f459-f460-48d9-87c1-9cbe4c670eeb` | 20/11 13:18 | `audit-c1-tools-call.json` |
  1047. | C2 | ✅ Bloqueo 13:21:40–13:27:08; el agente recibe `MCP HTTP 403` y **llegan 0 eventos** al MCP | 20/11 13:23 | `audit-c2-blocked.json` |
  1048. | C3 | ✅ Restaurado; requestId `6e02878a-3914-44f7-84bd-25aeb48dce73` | 20/11 13:28 | `audit-c2-c3.json` |
  1049. | E1 | ✅ Teams, sin inicio de sesión del agente; 0 clics (reutilizó la conexión creada en Copilot Studio); requestId `4267dae3-ae7f-47a8-96fd-988685ef5e8e` | 20/11 13:46 | `audit-e1-teams.json` |
  1050. | E2 | ✅ Segundo usuario piloto (Aadi Kapoor), con su propio `objectId`; requestId `50aad32e-fa2e-4e44-af00-b80f4b6acccb`. Requirió los requisitos 2 y 3 del Paso 8 | 20/11 15:03 | `audit-e2-teams-aadi.json` |
  1051. | E3 | ⏳ Pendiente. Andre Lawson no está en el grupo piloto, así que tampoco tiene acceso al entorno: se espera el rechazo **en Power Platform**, antes de llegar a Entra | — | — |
  1052. | E4 | ⏳ Pendiente | — | — |
  1053. | E5 | ⏳ Pendiente | — | — |
  1054. **Opción 2C: MCP en GCP por VPN**
  1055. | # | Resultado | Fecha (UTC) | Evidencia |
  1056. |---|---|---|---|
  1057. | G1 | ✅ VPN Azure ↔ GCP: 2 túneles `ESTABLISHED`, 2 sesiones BGP `UP`. Azure aprende `10.95.0.0/24` y `10.96.0.10/32`; GCP aprende `10.91.0.0/16`, `10.92.0.0/24` y `10.93.0.0/24` | 20/11 16:15–16:30 | `gcp-router-status.json`, `azure-vpngw-learned-routes.json` |
  1058. | G2 | ✅ Desde Azure (job de prueba): DNS → `10.96.0.10` (PSC), sin token → 401, MCP con token de Entra; `"runtime": "gcp-cloud-run-europe-west1"` | 20/11 16:20 | `probe-azure-to-gcp-vpn.jsonl`, `gcp-audit-probe.json` |
  1059. | G3 | ✅ Desde Power Platform (Canada Central y Canada East): DNS → `10.96.0.10`, TCP 443, TLS 1.3 con certificado de **Google Trust Services**, `sslErrors: None` | 20/11 16:40 | `pp-vnet-diagnostics-gcp.json` |
  1060. | G4 | ✅ Desde Internet: `/healthz` → **404** (Cloud Run rechaza el tráfico externo) | 20/11 16:10 | — |
  1061. | G5 | ✅ Agente nuevo en Copilot Studio: `tools/call` **delegada** atendida por el MCP de GCP. La respuesta muestra `"runtime": "gcp-cloud-run-europe-west1"`, `mode: delegated`, `admin@…` y cliente `<CONNECTOR_APP_ID>`. El requestId `2f603a9f-6570-4bbc-b86a-5be5d55fe715` está correlacionado en Cloud Run (4 sesiones MCP delegadas en total) | 20/11 18:36:48 | `gcp-audit-copilot-studio.json` |
  1062. | G6 | ✅ El agente y el MCP de ACA siguen funcionando tras activar *gateway transit* (diagnósticos y job de prueba) | 20/11 16:45 | — |
  1063. | G7 | ✅ **Teams con dos usuarios** en el agente de GCP: `admin@…` y **Aadi Kapoor** (sesión delegada 19:57:38, con su propia conexión). Para Aadi hizo falta compartir el agente y dar lectura del conector al grupo (Paso 8) | 20/11 19:25–19:57 | `gcp-audit-teams-aadi.json` |
  1064. ---
  1065. ## 6. Troubleshooting
  1066. Problemas encontrados durante el montaje, agrupados por área. La columna **Visto** indica si ocurrió
  1067. en el laboratorio (✔) o si es un caso previsto (·).
  1068. ### Diagnóstico rápido: «la herramienta falla»
  1069. ```mermaid
  1070. flowchart TD
  1071. A["La herramienta MCP falla"] --> B{"¿Hay llamadas en el registro del MCP?<br/>(laboratorio: show-mcp-audit.ps1)"}
  1072. B -- "No" --> C{"¿Error 403 en el agente?"}
  1073. C -- "Sí" --> C1["Bloqueo de red delante del MCP:<br/>falta la subred PP en la restricción de IP de ACA<br/>o en el firewall del MCP externo"]
  1074. C -- "No / timeout" --> C2["Ruta de red o DNS:<br/>pp-vnet-diagnostics.ps1, Enterprise Policy Linked,<br/>VPN/BGP y DNS del hub (ver 6.6)"]
  1075. B -- "Sí" --> D{"¿Qué estado registra?"}
  1076. D -- "401" --> D1["Token inválido: aud, iss, tid, exp o firma"]
  1077. D -- "403" --> D2["Cliente no permitido, sin rol MCP.User<br/>o sin scope MCP.Access"]
  1078. D -- "200" --> D3["El MCP respondió: revisar el agente<br/>(instrucciones, versión publicada)"]
  1079. A --> E{"¿Falla antes de llamar,<br/>al conectar o instalar?"}
  1080. E -- "Sí" --> E1["Ver 6.3, 6.4 y 6.5"]
  1081. ```
  1082. ### 6.1 Azure y despliegue
  1083. | Síntoma | Causa | Solución | Visto |
  1084. |---|---|---|---|
  1085. | `RequestDisallowedByAzure` … `locationineligible` en West Europe | La suscripción no admite nuevos recursos en esa región | Usar otra región para el backend (North Europe) y, para Power Platform, una suscripción que admita **las dos** regiones de la pareja. No intentar eludir la restricción | ✔ |
  1086. | Las regiones secundarias (Germany North, France South, Switzerland West, Norway West) no están disponibles | Son regiones de acceso restringido | Solicitar acceso a soporte o elegir una ubicación cuya pareja esté disponible | ✔ |
  1087. | Bicep `BCP120` al crear la zona DNS privada | El nombre de la zona depende de `defaultDomain`, que se conoce al final del despliegue | Crear la zona en un módulo ([infra/dns.bicep](./infra/dns.bicep)) | ✔ |
  1088. | `AppLogsConfiguration.Destination is invalid` con `'none'` | La API no acepta el literal `none` | Omitir la propiedad o usar `log-analytics` (configuración actual) | ✔ |
  1089. | `az rest` con JSON en línea: *Content-Type header*, *Unable to read JSON* | Entrecomillado de PowerShell/cmd en Windows | Cuerpo en fichero (`--body "@f.json"`) y `--headers Content-Type=application/json` | ✔ |
  1090. | `az rest` con URL que contiene paréntesis: *No se esperaba … en este momento* | `az.cmd` pasa por `cmd.exe`, que interpreta los paréntesis | Usar `Invoke-RestMethod` con `az account get-access-token` (como en `grant-connector-access.ps1`) | ✔ |
  1091. | `az monitor log-analytics query` se queda esperando (*EOF when reading a line*) | Intenta instalar una extensión de forma interactiva | Consultar la API `api.loganalytics.io` con `az rest` (`show-mcp-audit.ps1`) | ✔ |
  1092. | *What-if* marca cambios en `ipSecurityRestrictions` sin haber cambiado nada | Solo cambia el orden de las reglas, por las pruebas C2 y C3 | Ignorar o redesplegar con `deploy-mcp-app.ps1` | ✔ |
  1093. ### 6.2 Entorno Power Platform y VNet Support
  1094. | Síntoma | Causa | Solución | Visto |
  1095. |---|---|---|---|
  1096. | `pac admin create`: *The argument --user is only supported for Developer environment* | Parámetro exclusivo de entornos Developer | Quitar `--user` | ✔ |
  1097. | `pac admin create --region europe`: *macroRegion 'europe' is not valid* | El tenant usa selección por **macrorregión** | Consultar `pac environment-management get-supported-locations` y usar `--macro-region` | ✔ |
  1098. | No se puede garantizar VNet Support antes de crear el entorno | La macrorregión EU/EFTA puede asignar ubicaciones que no están en la tabla de VNet (p. ej. Polonia) | Elegir una macrorregión cuyas ubicaciones posibles estén soportadas, o fijar la región con Advanced Data Residency | ✔ |
  1099. | No se instala `Microsoft.PowerPlatform.EnterprisePolicies` (fallo TLS con PSGallery) | Restricción de red local; además, el módulo requiere Az PowerShell | Vincular la política con la API BAP (Paso 4.4) y diagnosticar con `pp-vnet-diagnostics.ps1` | ✔ |
  1100. | Diagnósticos `/plex` devuelven **503** justo después de vincular | La red delegada aún se está inicializando | Esperar (hasta 30 min) y repetir | ✔ |
  1101. | DNS correcto en una región pero no en la otra | Falta el enlace del DNS privado, el peering o el DNS personalizado en la segunda VNet | Revisar los parámetros de `pp-network.bicep`; las dos VNets necesitan la misma configuración | · |
  1102. | Hay que cambiar el DNS de las VNets delegadas | No se puede cambiar con la política vinculada | Desvincular, cambiar, esperar 30 min y volver a vincular. Mejor dejarlo definido antes del Paso 4.4 | · |
  1103. | Redesplegar `pp-network.bicep` quita un NSG de las subredes | Azure creó y asoció NSG automáticamente después del despliegue | Declararlos en `subnetNsgIds` (como en `pp-network.lab.parameters.json`) | ✔ |
  1104. | Conector creado antes de vincular la VNet no usa la red privada | Requisito documentado | Volver a guardar el conector tras vincular el entorno | · |
  1105. ### 6.3 Entra ID, OAuth y conexión
  1106. | Síntoma | Causa | Solución | Visto |
  1107. |---|---|---|---|
  1108. | `set-connector-redirect.ps1`: *No se encuentra un parámetro … "Value"* | Se ejecutaron el script y `Set-Clipboard` en la misma línea | Ejecutarlos en **líneas separadas** | ✔ |
  1109. | Hay dos secretos en la aplicación cliente | `new-connector-secret.ps1` se ejecutó dos veces | Revocar el que no se use (`az ad app credential delete`) cuando la conexión esté confirmada | ✔ |
  1110. | El tipo *Dynamic discovery* o *Dynamic* no funciona con Entra | Entra ID no admite registro dinámico de clientes (DCR) | Usar **Manual** | · |
  1111. | `AADSTS50011` al conectar | La redirect URI no coincide | Registrar la callback URL exacta (Paso 6.3) | · |
  1112. | `AADSTS50105` al conectar | Usuario sin el rol `MCP.User` (asignación obligatoria) | Añadirlo al grupo piloto si debe tener acceso. Es el comportamiento esperado para usuarios no autorizados | · |
  1113. | Pantalla de consentimiento para el usuario | Falta consentimiento de administrador, o se pide `offline_access` | Conceder consentimiento a `MCP.Access` (Paso 5); decidir expresamente si se concede `offline_access` | · |
  1114. | El usuario tiene que reconectar con frecuencia | No hay refresh token (`offline_access` no concedido) | Valorar conceder `offline_access` (prueba E4) | · |
  1115. ### 6.4 Copilot Studio y Teams
  1116. | Síntoma | Causa | Solución | Visto |
  1117. |---|---|---|---|
  1118. | *You don't have permission to use this tool … Authorization · 403* / `MCP Error -32603: MCP HTTP 403`, **sin llamadas en el registro del MCP** | Bloqueo de red delante del MCP (restricción de IP de ACA o firewall del MCP externo), no de permisos. **El agente lo atribuye a permisos o credenciales** | Laboratorio: `toggle-pp-access.ps1 -Mode Show`. MCP externo: revisar la regla del firewall. Las subredes PP deben estar permitidas | ✔ (C2) |
  1119. | La herramienta no aparece o no lista `iam_connection_check` | El MCP no es alcanzable, o el token no es válido en `tools/list` | Ver el diagrama de diagnóstico rápido | · |
  1120. | No aparecen *Opciones de disponibilidad* ni *Copiar vínculo* en el canal de Teams | La interfaz actual es distinta de la documentación | Usar las pestañas **Disponibilidad** y **Usar y compartir → Ver en Teams**, y copiar el enlace de instalación | ✔ |
  1121. | `AppDefinitionDoesntExist` / *No se puede cargar el paquete de la aplicación* al pulsar **Agregar** | Se cambió la configuración del canal después de publicar, o aún no se ha propagado. **Ocurrió en la primera instalación de los dos agentes** | **Publicar de nuevo**, esperar unos 5 min, recargar Teams con Ctrl+F5 y repetir. Alternativa: descargar el manifiesto y cargarlo como aplicación personalizada | ✔✔ |
  1122. | El agente sigue mostrando el nombre antiguo en Teams tras renombrarlo | Los datos del agente se copian al instalarlo y no se actualizan en las instalaciones existentes | Revisar **Canales → Información acerca de**, publicar, y que cada usuario **desinstale y vuelva a instalar** el agente (las conexiones se conservan) | ✔ |
  1123. | La autenticación de la herramienta falla siempre en Teams | El agente usa *Authenticate manually* sin la configuración SSO de Teams | Usar *Authenticate with Microsoft*, o completar la configuración SSO manual (app `api://botid-{teamsbotid}` y clientes de Teams preautorizados) | · |
  1124. | Los cambios del agente no se ven en Teams | Conversación iniciada con la versión anterior | Publicar y escribir `start over` en el chat | · |
  1125. ### 6.5 Acceso de otros usuarios
  1126. | Síntoma | Causa | Solución | Visto |
  1127. |---|---|---|---|
  1128. | *Su organización impidió la instalación de este agente* | El agente no está compartido con el usuario (o las políticas de M365/Teams lo bloquean) | Copilot Studio → **…** → **Compartir** con permiso de *usuario*. Si persiste, revisar las políticas ([documentación](https://learn.microsoft.com/en-us/troubleshoot/power-platform/copilot-studio/authoring/prevent-agent-install)) | ✔ |
  1129. | El grupo no aparece al buscar en **Compartir** | El selector nuevo no encuentra grupos de seguridad **sin correo** | Compartir con usuarios individuales, o usar *Use Classic Sharing*. En producción, valorar grupos con correo habilitado | ✔ |
  1130. | *Connector information unavailable* al crear la conexión | El conector del asistente MCP es un **conector de solución** de Dataverse. No se comparte desde Power Apps (`OperationNotSupportedForSolutionCustomConnectors`) y, desde octubre de 2026 (MC1520706), el rol *Basic User* no puede leerlo si no se comparte | `.\tools\grant-connector-access.ps1` | ✔ |
  1131. | El usuario no aparece en Dataverse y no puede crear la conexión | No pertenece al grupo de seguridad del entorno | Añadirlo al grupo, si debe tener acceso | ✔ (Andre) |
  1132. ### 6.6 Conectividad con un MCP externo (GCP, on-premises u otra red)
  1133. Casos previstos, no observados en el laboratorio porque su MCP está en Azure. Usa
  1134. `pp-vnet-diagnostics.ps1` para saber en qué capa falla: DNS, TCP o TLS.
  1135. | Síntoma (diagnóstico del Paso 4.5) | Causa probable | Solución |
  1136. |---|---|---|
  1137. | DNS no resuelve o devuelve una IP pública | Las VNets de Power Platform usan Azure DNS en lugar del resolver, o falta la regla de reenvío para la zona del MCP | `dnsServers` = IP del *inbound endpoint* del Private Resolver; regla de reenvío hacia el *inbound forwarder* de Cloud DNS o el DNS corporativo. Si la política ya está vinculada, ver 6.2 |
  1138. | DNS correcto, **TCP falla** en las dos regiones | La VPN o ExpressRoute no está conectada, falta *gateway transit* o no se anuncian las rutas | Túneles y BGP establecidos; peering con `useRemoteGateways`/`allowGatewayTransit`; rutas efectivas en el hub |
  1139. | DNS correcto, TCP falla **en una sola región** | Falta el peering, la ruta o la regla de firewall de una de las dos subredes delegadas | Anunciar **los dos** rangos y permitirlos en el firewall del MCP |
  1140. | TCP falla de forma intermitente | Enrutamiento asimétrico por varios caminos (VPN e Interconnect, varios hubs) o NAT intermedio | Revisar rutas de vuelta y prioridades BGP; evitar NAT o permitir las IP traducidas |
  1141. | TCP correcto, **TLS falla** | Certificado de CA interna, autofirmado, cadena incompleta, SAN distinto del FQDN o TLS inferior a 1.2 | Ver [2.6](#26-certificado-tls-del-mcp-qué-es-una-ca-y-qué-exige-power-platform): certificado de **CA pública** con la cadena completa, o un front privado en Azure con certificado público |
  1142. | Red y TLS correctos, pero el MCP devuelve **404/405** | No es un endpoint Streamable HTTP, o la ruta es incorrecta | Copilot Studio solo admite Streamable HTTP (`POST` a la ruta MCP); SSE no está soportado |
  1143. | El MCP devuelve **401** con tokens válidos | El MCP no alcanza `login.microsoftonline.com` para descargar las claves JWKS, o valida un `aud` o `iss` distinto | Permitir la salida HTTPS del MCP hacia Entra; revisar el contrato de la sección 3.1 |
  1144. | El MCP devuelve **403** | `azp` del cliente del conector no permitido, o falta el rol `MCP.User` o el scope | Añadir el client ID del Paso 5 a la lista de clientes permitidos del MCP |
  1145. | Rangos IP en conflicto al crear el peering o la VPN | Solapamiento entre Azure, GCP y on-premises | Elegir rangos libres para las subredes delegadas **antes** de vincular (no se pueden cambiar después) |
  1146. ### 6.7 MCP en GCP a través de VPN (laboratorio)
  1147. Problemas encontrados al montar la opción 2C.
  1148. | Síntoma | Causa | Solución | Visto |
  1149. |---|---|---|---|
  1150. | `gcloud`: *Reauthentication failed. cannot prompt during non-interactive execution* | La sesión de gcloud caducó | `gcloud auth login <cuenta>` en una terminal interactiva | ✔ |
  1151. | `Required 'compute.networks.list' permission` | La cuenta solo tenía roles de Vertex AI y Cloud Run | Asignar `compute.networkAdmin`, `servicedirectory.editor` y `dns.admin` (2C.1); retirarlos al terminar | ✔ |
  1152. | `gcloud run deploy --source`: *PERMISSION_DENIED* (Cloud Build `defaultServiceAccount` 403) | `--source` construye con Cloud Build y falta `cloudbuild.builds.create` | Construir en ACR y copiar la imagen a Artifact Registry con `crane` (2C.6), o pedir el rol de Cloud Build | ✔ |
  1153. | Docker local no disponible (*dockerDesktopLinuxEngine*) | Docker Desktop no está en marcha | No hace falta: `az acr build` + `crane copy` | ✔ |
  1154. | `az acr build` falla en `FROM node:…` con *Client.Timeout exceeded* | Fallo temporal al descargar desde Docker Hub | Reintentar | ✔ |
  1155. | `gcloud run deploy`: *Label value … violates format constraints* | PowerShell interpreta la coma de `--labels a=b,c=d` como separador de array | Poner el valor entre comillas simples | ✔ |
  1156. | El MCP de Cloud Run responde **404** desde Internet | Es lo esperado con `--ingress internal` | Ninguna; prueba de que no está expuesto | ✔ |
  1157. | Redesplegar `main.bicep` en el laboratorio: el *what-if* elimina los peerings de la VNet hub | La plantilla base no declara los peerings, que crea `pp-network.bicep` | No redesplegar la base en un laboratorio existente; añadir la `GatewaySubnet` con `az network vnet subnet create` | ✔ |
  1158. | `EnterprisePolicyUpdateNotAllowed` al redesplegar `pp-network.bicep` | Una política **vinculada** no se puede modificar, ni siquiera con los mismos valores. Los peerings sí se actualizan | `manageEnterprisePolicy=false` una vez vinculada | ✔ |
  1159. | Diagnósticos de Power Platform devuelven **503** tras activar *gateway transit* | La red delegada se reinicializa tras cambiar los peerings | Esperar unos minutos y repetir | ✔ |
  1160. | `az containerapp job start --env-vars …` arranca el servidor y falla con *Missing or invalid TENANT_ID* | Al sobrescribir el contenedor se usa el comando por defecto de la imagen | Añadir `--command node --args src/probe.mjs` | ✔ |
  1161. | `AADSTS50011` al conectar justo después de registrar la callback | El cambio en la aplicación de Entra tarda en propagarse | Esperar 1-2 minutos y reintentar | ✔ |
  1162. | Túneles `ESTABLISHED` pero sin rutas aprendidas | Falta la sesión BGP, las direcciones APIPA no coinciden o no se anuncia la IP del PSC | Comprobar que las APIPA coinciden (`169.254.21.x` y `169.254.22.x`) y el anuncio personalizado del Cloud Router (`10.96.0.10/32`) | · |
  1163. | DNS de `*.run.app` devuelve una IP pública desde Power Platform | La zona privada no está enlazada a la VNet delegada, o no tiene el nombre exacto del servicio | Enlazar la zona de `gcp-mcp-dns.bicep` a **las dos** VNets de Power Platform | · |
  1164. | Cloud Run responde **403** (de Google, no del MCP) | Falta `--no-invoker-iam-check` y Cloud Run exige un token de identidad de Google | Desplegar con `--no-invoker-iam-check`; la identidad la valida el MCP | · |
  1165. ### 6.8 Información para abrir un caso con Unified
  1166. Recoge:
  1167. - **Hora UTC** del fallo.
  1168. - **IDs:** Environment ID, ID del agente y nombre interno del conector.
  1169. - **Identificadores de la petición:** correlation ID de Power Platform y `requestId` de la auditoría.
  1170. - **Código HTTP**, la salida de `pp-vnet-diagnostics.ps1` y la configuración de la entrada de ACA o
  1171. del firewall del MCP. Si el MCP es externo: estado de la VPN, rutas efectivas del hub y reglas del
  1172. Private Resolver.
  1173. **No adjuntes** tokens, refresh tokens, secretos, cookies ni datos personales. No uses la
  1174. publicación del MCP en Internet como «solución» al requisito de conectividad privada.
  1175. ---
  1176. ## 7. Recomendaciones
  1177. 1. **Sustituir el gateway por VNet Support**, con el entorno como Managed Environment. Antes de
  1178. nada, comprobar la región del entorno y que la suscripción admite **las dos** regiones de la pareja.
  1179. 2. **Conectar las subredes delegadas como *spokes* del hub** que ya tenga (o tendrá) la VPN o la
  1180. interconexión con GCP y on-premises, con *gateway transit*. No hace falta migrar los MCP a Azure.
  1181. 3. **Certificado de CA pública** en el punto de entrada privado de los MCP (F5 o front en Azure).
  1182. Es un requisito oficial; ver [2.6](#26-certificado-tls-del-mcp-qué-es-una-ca-y-qué-exige-power-platform).
  1183. **Primera pregunta para el equipo propietario del MCP:** qué certificado presenta hoy el F5 (emisor y nombre).
  1184. 4. **DNS privado resoluble desde las dos regiones** (Private Resolver con reenvío a Cloud DNS o al
  1185. DNS corporativo), definido **antes** de vincular la política.
  1186. 5. **Contrato JWT de Entra en los MCP** de GCP u on-premises: validar emisor, audiencia, scope,
  1187. cliente permitido y rol de usuario (sección 3.1).
  1188. 6. **Gobierno de acceso por grupos:**
  1189. - **grupo del entorno**, para quién entra en Power Platform;
  1190. - **grupo de la herramienta**, con el rol `MCP.User`, para quién llama al MCP;
  1191. - **compartir el agente** y **dar lectura del conector** a esos grupos.
  1192. Separar los dos grupos permite controlar por separado el acceso al agente y a la herramienta.
  1193. 7. **Políticas de Microsoft 365 y Teams** que permitan agentes de la organización para los usuarios
  1194. del piloto; para la difusión general, usar el catálogo de la organización con aprobación.
  1195. 8. **APIM interno** si hay varios MCP: TLS público, `validate-jwt`, cuotas y trazabilidad centralizados.
  1196. 9. **Operación:** alertas sobre 401 y 403, retención de la auditoría, rotación de secretos (o
  1197. credenciales federadas) y revisión ENS antes de la producción.
  1198. **Alternativas** si el conector con OAuth delegado y VNet fallara en su entorno (sin exponer los MCP):
  1199. - front APIM interno, si el problema es de TLS;
  1200. - autenticación del creador del agente con autorización en el MCP, que **pierde la identidad del
  1201. usuario** y solo sirve para herramientas de bajo riesgo;
  1202. - nodo HTTP en los temas, que no es MCP.
  1203. **Limitaciones conocidas:**
  1204. - el backend del laboratorio está en una sola región, sin alta disponibilidad;
  1205. - solo hay herramientas sintéticas;
  1206. - no se han hecho pruebas de carga ni una evaluación formal de cumplimiento.
  1207. ---
  1208. ## 8. Recursos del laboratorio, costes y retirada
  1209. | Recurso | Nombre (valores por defecto de `config/lab.config.example.json`) |
  1210. |---|---|
  1211. | Suscripción / tenant | `<SUBSCRIPTION_ID>` / `<TENANT_ID>` |
  1212. | Grupo de recursos | `rg-mcp-lab` (metadatos en West Europe; recursos en North Europe y Canadá) |
  1213. | Entorno ACA / app / job | `mcp-lab-env` (IP privada `10.91.1.235`) / `mcp-server` (imagen `mcp-server:v5`, la misma que en GCP; `MCP_RUNTIME=azure-container-apps-northeurope`) / `mcp-server-probe` |
  1214. | Endpoint MCP | `https://<MCP_HOST>/mcp` |
  1215. | ACR / Log Analytics | `<ACR_NAME>` / `mcp-lab-logs` (`<LOG_ANALYTICS_WORKSPACE_ID>`, 30 días, 1 GB/día) |
  1216. | Identidades administradas | `mcp-lab-runtime` (sin roles en la API) · `mcp-lab-probe` (`azure.probeClientId`, rol `MCP.Probe`) |
  1217. | Redes | `mcp-lab-vnet` (ACA, 10.91.0.0/16) · `mcp-lab-pp-canadacentral` (10.92.0.0/26) · `mcp-lab-pp-canadaeast` (10.93.0.0/26) · peerings globales · NSG creados automáticamente en las subredes |
  1218. | Enterprise Policy | `mcp-lab-pp-network` (`canada`, vinculada) |
  1219. | Entorno Power Platform | `MCP Private Lab` · `<ENVIRONMENT_ID>` · `<ORG_URL>` |
  1220. | Agente (Azure) / Teams | `Asistente MCP Azure VNet` · enlace de instalación con su `templateInstanceId` (Paso 7) |
  1221. | Conector (Dataverse) | `MCP Private Lab` (`powerPlatform.connectorDisplayName`) |
  1222. | Equipo Dataverse | Vinculado al grupo piloto, rol Usuario Basic (`grant-connector-access.ps1`) |
  1223. | Entra: API del MCP | appId `<API_APP_ID>`; roles `MCP.User` (`8d0f6a2e-…`) y `MCP.Probe` (`396bf063-…`) |
  1224. | Entra: cliente del conector | appId `<CONNECTOR_APP_ID>`; consentimiento solo `MCP.Access`; una redirect URI y un secreto (30 días) por conector: ACA y, con la opción 2C, GCP |
  1225. | Entra: grupo piloto | `MCP-Lab-Pilot` (`entra.pilotGroupObjectId`): usuarios del piloto |
  1226. | **Opción 2C · Azure** | VPN Gateway `mcp-lab-vpngw` (VpnGw1AZ) + IP `mcp-lab-vpngw-pip` (`<AZURE_VPNGW_IP>`) · `GatewaySubnet` 10.91.255.0/27 · gateways de red local `mcp-lab-gcp-if0/if1` · conexiones `mcp-lab-gcp-conn0/conn1` · zona DNS privada `<CLOUD_RUN_HOST>` · peerings PP con *gateway transit* |
  1227. | **Opción 2C · GCP** (`<GCP_PROJECT_ID>`) | VPC `mcp-lab-vpc` y subred `mcp-lab-subnet` · dirección y endpoint PSC `mcplabpsc-ip`/`mcplabpsc` · HA VPN `mcp-lab-havpn` · gateway externo `mcp-lab-azure-gw` · Cloud Router `mcp-lab-router` · túneles `mcp-lab-tunnel0/1` · Cloud Run `mcp-server-gcp` · Artifact Registry `mcp-lab` |
  1228. | **Opción 2C · Copilot Studio** | Agente `Asistente MCP GCP VNet` · conector `MCP GCP privado` (compartido con el equipo del grupo piloto) |
  1229. | **Opción 2C · permisos y ficheros locales** | Roles de GCP asignados a `<tu-cuenta-gcp>`: `compute.networkAdmin`, `servicedirectory.editor` y `dns.admin` · clave IPsec en `gcp.pskFile` (DPAPI) · `crane` en `%LOCALAPPDATA%\mcp-lab\crane` |
  1230. **Costes recurrentes:**
  1231. - Container Apps (una réplica mínima), ACR Basic, Log Analytics, tráfico de peering global y capacidad
  1232. de Dataverse del entorno.
  1233. - **Opción 2C:** unos **7 USD al día** (VPN Gateway VpnGw1AZ y dos túneles de HA VPN), más el tráfico
  1234. de salida. Cloud Run con `min-instances 0` apenas tiene coste.
  1235. **Orden de retirada** (cada paso requiere autorización expresa; nada se borra automáticamente):
  1236. 1. **Opción 2C, primero:**
  1237. - Copilot Studio: eliminar el agente `Asistente MCP GCP VNet` y su conector.
  1238. - GCP:
  1239. ```powershell
  1240. gcloud run services delete mcp-server-gcp --region europe-west1
  1241. gcloud artifacts repositories delete mcp-lab --location europe-west1
  1242. gcloud compute vpn-tunnels delete mcp-lab-tunnel0 mcp-lab-tunnel1 --region europe-west1
  1243. gcloud compute routers delete mcp-lab-router --region europe-west1
  1244. gcloud compute vpn-gateways delete mcp-lab-havpn --region europe-west1
  1245. gcloud compute external-vpn-gateways delete mcp-lab-azure-gw
  1246. gcloud compute forwarding-rules delete mcplabpsc --global
  1247. gcloud compute addresses delete mcplabpsc-ip --global
  1248. gcloud compute networks subnets delete mcp-lab-subnet --region europe-west1
  1249. gcloud compute networks delete mcp-lab-vpc
  1250. ```
  1251. - Azure: eliminar las conexiones, los gateways de red local, el VPN Gateway, su IP pública y la zona
  1252. DNS privada. Después, redesplegar `pp-network.bicep` con `useRemoteGateways=false`.
  1253. - Retirar los tres roles de GCP con `gcloud projects remove-iam-policy-binding`.
  1254. - Borrar `%LOCALAPPDATA%\mcp-lab`, que contiene la clave IPsec y `crane`.
  1255. 2. Desvincular la Enterprise Policy del entorno (`…/NetworkInjection/unlink`, mismo cuerpo que en el Paso 4.4).
  1256. 3. Eliminar el entorno Power Platform (borra Dataverse, los agentes y los conectores).
  1257. 4. Eliminar el grupo de recursos `rg-mcp-lab`.
  1258. 5. Eliminar en Entra las aplicaciones API y cliente, y el grupo piloto.
  1259. ---
  1260. ## 9. Contenido del repositorio
  1261. | Ruta | Contenido |
  1262. |---|---|
  1263. | [config/lab.config.example.json](./config/lab.config.example.json) | Plantilla de la configuración local (`config/lab.config.json`, ignorado por git) que leen los scripts |
  1264. | [src/](./src/) | Servidor MCP (`server.mjs`, `app.mjs`, `auth.mjs`) y job de prueba (`probe.mjs`) |
  1265. | [test/](./test/) | Pruebas locales (`npm test`) |
  1266. | [infra/main.bicep](./infra/main.bicep) · [dns.bicep](./infra/dns.bicep) | VNet, ACA interno, DNS privado, ACR, identidades y Log Analytics |
  1267. | [infra/app.bicep](./infra/app.bicep) | App MCP (restricciones de IP y clientes permitidos) y job de prueba |
  1268. | [infra/pp-network.bicep](./infra/pp-network.bicep) | VNets delegadas a Power Platform, conexión con el MCP (peering directo o hub con *gateway transit*), DNS y Enterprise Policy |
  1269. | [infra/pp-network.lab.example.parameters.json](./infra/pp-network.lab.example.parameters.json) | Plantilla de parámetros del laboratorio (MCP en ACA); se copia como `pp-network.lab.parameters.json` (ignorado por git) |
  1270. | [infra/pp-network.hub.example.parameters.json](./infra/pp-network.hub.example.parameters.json) | Plantilla de parámetros para un MCP externo (GCP u on-premises) a través del hub |
  1271. | [infra/modules/](./infra/modules/) | Peering y enlace DNS en otro grupo de recursos o suscripción |
  1272. | [infra/*.json](./infra/) | Plantillas de Entra (con marcadores `<...>`): API, cliente del conector y rol de prueba |
  1273. | [connector/mcp-openapi.yaml](./connector/mcp-openapi.yaml) | Alternativa al asistente: plantilla OpenAPI para un conector personalizado MCP (sustituir `<MCP_HOST>`, `<TENANT_ID>` y `<API_APP_ID>`) |
  1274. | [tools/lab-config.ps1](./tools/lab-config.ps1) | Funciones comunes de los scripts para leer `config/lab.config.json` |
  1275. | [tools/deploy-mcp-app.ps1](./tools/deploy-mcp-app.ps1) | Despliega la app MCP (`-WhatIf` para previsualizar) |
  1276. | [tools/pp-vnet-diagnostics.ps1](./tools/pp-vnet-diagnostics.ps1) | DNS, TCP y TLS desde dentro de Power Platform, por región |
  1277. | [tools/new-connector-secret.ps1](./tools/new-connector-secret.ps1) | Genera un secreto de cliente y lo copia al portapapeles sin mostrarlo |
  1278. | [tools/set-connector-redirect.ps1](./tools/set-connector-redirect.ps1) | Registra la callback URL del conector |
  1279. | [tools/grant-connector-access.ps1](./tools/grant-connector-access.ps1) | Da a un grupo lectura del conector en Dataverse |
  1280. | [tools/show-mcp-audit.ps1](./tools/show-mcp-audit.ps1) | Auditoría de llamadas al MCP, con el usuario de cada una |
  1281. | [tools/toggle-pp-access.ps1](./tools/toggle-pp-access.ps1) | Bloquea o restaura las subredes de Power Platform (prueba C2) |
  1282. | [infra/vpn-gateway.bicep](./infra/vpn-gateway.bicep) | Opción 2C: VPN Gateway de Azure con BGP y direcciones APIPA para HA VPN de GCP |
  1283. | [infra/vpn-gcp-connections.bicep](./infra/vpn-gcp-connections.bicep) | Opción 2C: gateways de red local y conexiones IPsec/BGP hacia las dos interfaces de HA VPN |
  1284. | [infra/gcp-mcp-dns.bicep](./infra/gcp-mcp-dns.bicep) | Opción 2C: zona DNS privada solo para la URL `run.app` del MCP → IP del endpoint PSC |
  1285. | [infra/gcp/setup-gcp-network.ps1](./infra/gcp/setup-gcp-network.ps1) | Opción 2C: VPC, endpoint PSC, HA VPN, Cloud Router, túneles y BGP en GCP (idempotente) |
  1286. | [tools/show-gcp-mcp-audit.ps1](./tools/show-gcp-mcp-audit.ps1) | Opción 2C: auditoría de llamadas al MCP de Cloud Run, con el usuario de cada una |
  1287. ---
  1288. ## 10. Referencias
  1289. Documentación oficial de Microsoft utilizada para diseñar, montar y validar la solución, agrupada por
  1290. tema. Los enlaces apuntan a la versión en inglés de Microsoft Learn, que es la que se actualiza antes;
  1291. cambiando `en-us` por `es-es` en la URL se obtiene la versión en español.
  1292. ### 10.1 Power Platform: VNet Support y entornos
  1293. - [Virtual Network support overview](https://learn.microsoft.com/en-us/power-platform/admin/vnet-support-overview): servicios y conectores admitidos, regiones por geografía, dimensionamiento de subredes y preguntas frecuentes (DNS personalizado, hub-spoke)
  1294. - [FAQ: certificados de CA no reconocidas (CA interna) no admitidos](https://learn.microsoft.com/en-us/power-platform/admin/vnet-support-overview#my-on-premises-endpoint-tls-certificates-arent-signed-by-well-known-root-certification-authorities-ca-do-you-support-unknown-certificates)
  1295. - [Set up Virtual Network support for Power Platform](https://learn.microsoft.com/en-us/power-platform/admin/vnet-support-setup-configure): subredes delegadas, Enterprise Policy y vinculación al entorno
  1296. - [Troubleshoot virtual network issues](https://learn.microsoft.com/en-us/troubleshoot/power-platform/administration/virtual-network): diagnósticos de DNS, conectividad y TLS desde el entorno
  1297. - [Managed Environments overview](https://learn.microsoft.com/en-us/power-platform/admin/managed-environment-overview) y [Enable Managed Environments](https://learn.microsoft.com/en-us/power-platform/admin/managed-environment-enable)
  1298. - [Power Platform macro regions](https://learn.microsoft.com/en-us/power-platform/admin/macro-regions): ubicación asignada al crear un entorno
  1299. - [Power Platform CLI: `pac admin`](https://learn.microsoft.com/en-us/power-platform/developer/cli/reference/admin) y [`pac environment-management`](https://learn.microsoft.com/en-us/power-platform/developer/cli/reference/environment-management)
  1300. - [Manage group teams](https://learn.microsoft.com/en-us/power-platform/admin/manage-group-teams): equipos de Dataverse vinculados a grupos de Entra ID
  1301. - [GrantAccess (Dataverse Web API)](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/reference/grantaccess): compartir el registro del conector con el equipo
  1302. ### 10.2 Conectores personalizados
  1303. - [Custom connectors overview](https://learn.microsoft.com/en-us/connectors/custom-connectors/): autenticación OAuth, uso con On-premises Data Gateway y VNet, limitaciones
  1304. - [Share a custom connector in your organization](https://learn.microsoft.com/en-us/connectors/custom-connectors/share)
  1305. ### 10.3 Copilot Studio y Microsoft Teams
  1306. - [Extend your agent with Model Context Protocol](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp): transporte Streamable HTTP y requisitos del servidor MCP
  1307. - [Connect to an existing MCP server](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent): asistente MCP con OAuth 2.0 manual
  1308. - [Configure user authentication for tools](https://learn.microsoft.com/en-us/microsoft-copilot-studio/configure-enduser-authentication): credenciales del usuario final frente a las del creador
  1309. - [Configure user authentication in Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/configuration-end-user-authentication): *Authenticate with Microsoft*
  1310. - [Configure single sign-on with Microsoft Entra ID for agents in Teams](https://learn.microsoft.com/en-us/microsoft-copilot-studio/configure-sso-teams)
  1311. - [Virtual network support in Copilot Studio](https://learn.microsoft.com/en-us/microsoft-copilot-studio/admin-network-isolation-vnet)
  1312. - [Publish an agent to Microsoft Teams and Microsoft 365](https://learn.microsoft.com/en-us/microsoft-copilot-studio/publication-add-bot-to-microsoft-teams)
  1313. - [Share agents with other users](https://learn.microsoft.com/en-us/microsoft-copilot-studio/admin-share-bots)
  1314. - [*Your organization has prevented this agent from being installed*](https://learn.microsoft.com/en-us/troubleshoot/power-platform/copilot-studio/authoring/prevent-agent-install)
  1315. - [Manage agents in the Microsoft 365 admin center](https://learn.microsoft.com/en-us/microsoft-365/admin/manage/manage-copilot-agents-integrated-apps)
  1316. - [Manage custom app policies and settings in Microsoft Teams](https://learn.microsoft.com/en-us/microsoftteams/teams-custom-app-policies-and-settings)
  1317. ### 10.4 Microsoft Entra ID y Microsoft Graph
  1318. - [Microsoft identity platform access tokens](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens): claims `iss`, `aud`, `tid`, `scp`, `azp`, `roles` y validación de la firma
  1319. - [OAuth 2.0 authorization code flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow): flujo que usa el conector para el usuario
  1320. - [Add app roles and get them from a token](https://learn.microsoft.com/en-us/entra/identity-platform/howto-add-app-roles-in-apps): roles `MCP.User` y `MCP.Probe`
  1321. - [Restrict a Microsoft Entra app to a set of users](https://learn.microsoft.com/en-us/entra/identity-platform/howto-restrict-your-app-to-a-set-of-users) y [Assign users and groups to an application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal): asignación obligatoria
  1322. - [Grant an app role assignment for a service principal (Graph)](https://learn.microsoft.com/en-us/graph/api/serviceprincipal-post-approleassignedto)
  1323. - [Create oAuth2PermissionGrant (Graph)](https://learn.microsoft.com/en-us/graph/api/oauth2permissiongrant-post): consentimiento de administrador limitado a `MCP.Access`
  1324. ### 10.5 Azure: red, DNS y conectividad híbrida
  1325. - [Virtual network peering](https://learn.microsoft.com/en-us/azure/virtual-network/virtual-network-peering-overview)
  1326. - [Configure VPN gateway transit for virtual network peering](https://learn.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-peering-gateway-transit)
  1327. - [Configure BGP for Azure VPN Gateway](https://learn.microsoft.com/en-us/azure/vpn-gateway/bgp-howto): direcciones APIPA personalizadas para la VPN con Google Cloud
  1328. - [Azure Private DNS overview](https://learn.microsoft.com/en-us/azure/dns/private-dns-overview)
  1329. - [Azure DNS Private Resolver](https://learn.microsoft.com/en-us/azure/dns/dns-private-resolver-overview)
  1330. - [Hub-spoke network topology in Azure](https://learn.microsoft.com/en-us/azure/architecture/networking/architecture/hub-spoke)
  1331. ### 10.6 Azure: servidor MCP de laboratorio
  1332. - [Networking in Azure Container Apps environments](https://learn.microsoft.com/en-us/azure/container-apps/networking): entorno interno e *ingress*
  1333. - [Set up IP ingress restrictions in Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/ip-restrictions)
  1334. - [Jobs in Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/jobs): job de prueba
  1335. - [Build a container image with ACR Tasks](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-tutorial-quick-task): `az acr build`, sin Docker local
  1336. - [Monitor logs in Azure Container Apps with Log Analytics](https://learn.microsoft.com/en-us/azure/container-apps/log-monitoring) y [Azure Monitor Logs Query API](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/overview): auditoría de llamadas
  1337. ### 10.7 Google Cloud (opción 2C)
  1338. No es documentación de Microsoft, pero se usó para la parte de GCP:
  1339. - [Cloud Run: restringir el ingress (las peticiones por Cloud VPN se consideran internas)](https://cloud.google.com/run/docs/securing/ingress)
  1340. - [Cloud Run: redes privadas y acceso con Private Service Connect desde on-premises](https://cloud.google.com/run/docs/securing/private-networking)
  1341. - [HA VPN hacia Azure](https://cloud.google.com/network-connectivity/docs/vpn/tutorials/create-ha-vpn-connections-google-cloud-azure)
  1342. - [Endpoints de Private Service Connect para APIs de Google](https://cloud.google.com/vpc/docs/configure-private-service-connect-apis)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.