Conectar con una clave API
Una clave API es un secreto compartido que se envía en una cabecera. Las llamadas actúan como el usuario de servicio configurado, cuyas capacidades de WordPress y las puertas de escritura del sitio determinan el acceso.
El acceso sigue al usuario de servicio
Los ámbitos OAuth se aplican a las conexiones OAuth. Las llamadas con clave API pueden ejecutar escrituras compatibles cuando un usuario de servicio tiene las capacidades necesarias y la puerta de escritura correspondiente está abierta. La validación del esquema y las listas de campos permitidos siguen aplicándose.
Prefiere OAuth cuando cada cliente necesite sus propios ámbitos y revocación. Consulta Elegir un método de autenticación.
Generar una
- Abre Settings → POM AI → MCP server.
- En la tarjeta Credentials, selecciona Generate / rotate API key.
- Confirma el aviso, que advierte de que la clave existente dejará de funcionar.
- Copia la clave inmediatamente. Se muestra una sola vez.
Solo se almacena el hash. Después, el panel muestra únicamente los últimos cuatro caracteres, por lo que una clave que no copiaste no se puede recuperar: genera una nueva.
Las claves tienen este aspecto: pomai_mcp_ seguido de una cadena aleatoria.
Configurar el cliente
Envía la clave en esta cabecera:
X-POM-AI-MCP-API-Key: pomai_mcp_…La mayoría de los clientes la exponen como una cabecera personalizada, leyendo a menudo el valor desde una variable de entorno. No la envíes como Authorization: Bearer: una solicitud que incluya tanto una cabecera de clave API como una cabecera Bearer se rechaza por ambigua.
El usuario de servicio
El Service user ID en los ajustes de MCP decide como qué usuario de WordPress actúan las llamadas con clave API.
- Transporte estándar: sin un usuario de servicio válido, solo pueden ejecutarse las operaciones que permiten un actor de WordPress no autenticado; las escrituras requieren un actor configurado.
- WordPress MCP Adapter: se requiere un usuario de servicio válido con la capacidad
readincluso para inicializar la conexión. - Con un usuario de servicio válido: cada operación comprueba las capacidades de ese usuario. Las escrituras también requieren la puerta abierta correspondiente.
Elige un usuario que tenga solo las capacidades que la integración necesita. Mantén cerradas las puertas de escritura para una integración de solo lectura.
Una clave por sitio
Hay una única clave activa por sitio. Generar una nueva sustituye a la anterior, que deja de funcionar de inmediato.
En multisitio, cada sitio tiene su propia clave. Una clave de un sitio no funciona en otro.
Al ser compartida en lugar de por cliente, varias herramientas que usen la misma clave resultan indistinguibles en los registros, y revocarla las afecta a todas a la vez. Esa es la principal desventaja operativa respecto a OAuth.
Rotación y revocación
Generate / rotate API key emite una clave nueva e invalida la anterior. Todos los clientes que la usen dejan de funcionar hasta que se actualicen.
Revoke API key elimina la clave por completo, sin reemplazo. La autenticación con clave API falla entonces hasta que se genere una nueva.
Rota la clave cuando pueda haber quedado expuesta: pegada en un ticket, confirmada en un repositorio o en manos de alguien que se haya marchado. Ambas acciones quedan registradas en el registro de MCP.
Gestión de la clave
- Guárdala en un gestor de contraseñas o en un almacén de secretos, nunca en un documento ni en un ticket.
- Entrégasela al cliente mediante una variable de entorno en lugar de un archivo de configuración bajo control de versiones.
- Usa solo HTTPS; la clave viaja en una cabecera en cada solicitud.
- Rótala cuando alguien con acceso se marche.
- Desactiva Enable API key auth por completo si solo usas OAuth.
Comprobar que funciona
Inicializa la conexión MCP y, a continuación, envía tools/list usando las cabeceras de sesión de transporte necesarias. La lista describe el catálogo registrado; los permisos de ejecución se comprueban por separado. Verifica una lectura permitida y, para una configuración de solo lectura, verifica que se rechace una vista previa de escritura.
Luego revisa el panel de ajustes de MCP: el registro reciente debería mostrar la llamada con api_key como tipo de autenticación. Si el registro no muestra nada, la cabecera no llegó; ejecuta los diagnósticos, que informan de si se vio la cabecera de clave API.
Cuando falla
| Síntoma | Causa |
|---|---|
pom_ai_mcp_invalid_api_key |
Clave incorrecta o revocada |
pom_ai_mcp_api_key_disabled |
Enable API key auth está desactivado |
pom_ai_mcp_ambiguous_auth |
Se enviaron a la vez una cabecera Bearer y una clave API |
| Herramientas de escritura rechazadas | Falta de usuario de servicio, capacidades insuficientes, una puerta cerrada o una negativa de la lista de campos permitidos |
| La inicialización nativa devuelve HTTP 403 | El usuario de servicio falta o carece de read |
| Menos herramientas de las esperadas | Comprueba el tema y los plugins activos y vuelve a descubrir el catálogo |
| La cabecera nunca aparece en los diagnósticos | Algo en un nivel superior la está eliminando |
Siguiente
Conectar un cliente y, a continuación, haz tu primera solicitud de lectura.