Guía de LangSmith Tool Gateway: credenciales, tool kits, políticas y aprobaciones para llamadas de agentes
LangSmith Tool Gateway entró en beta pública el 19 de noviembre de 2026. Reúne en una sola capa gestionada las credenciales, la identidad y el acceso de las llamadas a herramientas que hacen los agentes. Esta guía sigue un modelo Ver / Actuar como / Permitir para explicar cómo registrar servidores MCP, crear tool kits, elegir entre identidad por usuario o clave de servicio y añadir políticas de bloqueo y aprobación. También repasa los límites documentados y dónde dejan de protegerte estos controles.
Qué es LangSmith Tool Gateway y por qué existe
Según la propia LangChain, LangSmith Tool Gateway es una capa gestionada de herramientas que se ocupa de las credenciales, la identidad y el acceso en cada llamada a herramientas de un agente. Se sitúa entre tus agentes y los servidores MCP a los que llaman. Así, cada agente deja de tener que resolver esas cuestiones por su cuenta.
LangChain lanzó Tool Gateway en beta pública el 19 de noviembre de 2026, como informó Unite.AI. La beta está disponible en los planes Plus y Enterprise de LangSmith. En LangSmith Cloud cubre las regiones GCP US, GCP EU, GCP APAC y AWS US. Azure US queda fuera.
Pensemos en el gran minorista estadounidense que LangChain describe en su anuncio de lanzamiento: su equipo de ingeniería ha creado más de 50 servidores MCP que exponen más de mil herramientas. Cada agente debería acceder solo a una parte pequeña y aprobada de ese catálogo, con credenciales adecuadas a su contexto. El gateway está pensado precisamente para someter a un único conjunto de controles esa dispersión de herramientas y credenciales repartidas entre muchos servidores y agentes.
Una advertencia antes de entrar en detalles. Los productos en beta cambian, y hay varios detalles de implementación que importan para que el código funcione: nombres de campos en las respuestas, ajustes de configuración, formatos de endpoint, cabeceras de autenticación, requisitos de transporte y qué planes incluyen cada función. Los ejemplos siguientes usan marcadores de posición para todo esto. Contrasta cada uno con la documentación vigente y con respuestas reales durante las pruebas, y copia los valores tal cual en lugar de suponerlos.
El modelo de gobernanza Ver / Actuar como / Permitir
El OWASP Gen AI Security Project define la Agencia Excesiva (Excessive Agency) como la vulnerabilidad que permite a un LLM realizar acciones dañinas en respuesta a salidas inesperadas, ambiguas o manipuladas. Sus tres causas habituales son la funcionalidad excesiva, los permisos excesivos y la autonomía excesiva.
Asociamos cada una de esas causas a uno de los controles del gateway y llamamos al resultado Ver / Actuar como / Permitir (See / Act As / Allow):
- Ver (funcionalidad excesiva): ¿qué herramientas ve este agente? Los tool kits.
- Actuar como (permisos excesivos): ¿qué credenciales lleva una llamada? La configuración de identidad.
- Permitir (autonomía excesiva): ¿debe ejecutarse esta llamada concreta? Las políticas de bloqueo y aprobación.
Una capa no compensa las carencias de otra. Un agente de reembolsos con un kit de dos herramientas sigue teniendo todo lo que permita su credencial. Si esa credencial es la clave de servicio del backend y ninguna política bloquea una herramienta destructiva, el kit pequeño ha reducido el menú sin reducir el riesgo.
Cómo recorre el gateway una llamada a una herramienta
Una llamada a una herramienta implica tres pasos de autenticación distintos, que se detallan en la página How Tool Gateway works. Para el diseño, dos de ellos son los que más importan. El llamante se autentica solo ante LangSmith. Después, Tool Gateway elige una credencial almacenada y la usa para autenticarse ante el servidor MCP. Por tanto, el llamante nunca tiene el token ni la clave de API del servidor. Es el mismo patrón que un proxy de credenciales que mantiene las claves de API fuera de los agentes de IA: el agente pide y el proxy guarda el secreto.
Este diseño encaja con las indicaciones de autorización de la especificación MCP. Cuando un servidor MCP llama a APIs de nivel superior, usa un token independiente emitido por el servidor de autorización correspondiente y no debe reenviar el token que recibió del cliente MCP. Los servidores de autorización también deberían emitir tokens de acceso de corta duración para reducir el impacto de una filtración.
Cuando un usuario no ha conectado su cuenta
Si una llamada necesita la credencial de un usuario y ese usuario no ha conectado su cuenta, la llamada devuelve un enlace de inicio de sesión. Un cliente compatible con la elicitación de URL de MCP muestra el enlace al usuario. Los demás clientes reciben una respuesta HTTP 428 con el enlace. Una vez que el usuario se conecta, las llamadas posteriores usan la credencial almacenada.
Recomendamos que tu cliente trate esta respuesta como un paso de inicio de sesión previsto y no como un error. Muestra el enlace, espera al usuario y reintenta una sola vez:
resp = call_tool(req)
if resp.status == 428:
link = sign_in_link_from(resp.body) # placeholder field name
show_sign_in(link)
await user_confirms_sign_in()
resp = call_tool(req) # retry once, never loopLo que el gateway no hace con las respuestas
La respuesta de cada servidor llega al llamante sin cambios. LangChain aconseja tratar la salida de las herramientas como una entrada no fiable para tu agente. El gateway no es un filtro de contenido. Defensas como la separación entre instrucciones y datos frente a la inyección de prompts siguen siendo responsabilidad tuya y forman parte del diseño del agente.
Configuración paso a paso: servidores, kits, modo de búsqueda y una primera petición
Las pantallas y las rutas de la API pueden cambiar durante la beta. Por eso estos pasos siguen los conceptos documentados en lugar de los clics.
- Registra cada servidor MCP. Añade el servidor para que sea el gateway, y no tu agente, quien se autentique ante él, y revisa la documentación de identidad antes de decidir qué credenciales deben llevar sus llamadas.
- Crea un kit por cada rol de agente. Elige herramientas de tus servidores registrados, nombra el kit según el rol al que sirve y mantenlo pequeño. La documentación de tool kits explica cómo crear y actualizar kits.
- Usa el modo de búsqueda con catálogos grandes. Si un rol necesita de verdad muchas herramientas, el modo de búsqueda evita cargarlas todas a la vez.
- Envía una primera petición desde tu backend. Un llamante de backend envía la clave de servicio junto con una cabecera X-LangSmith-Identity que indica el usuario en cuyo nombre actúa la llamada:
POST <your kit's MCP endpoint, as shown in LangSmith>
<auth header carrying the service key>
X-LangSmith-Identity: <user this call acts for>
<standard MCP tool call payload>Las líneas del endpoint y de autenticación son marcadores de posición, como se indicaba en la advertencia del principio. Toma los valores exactos de LangSmith y de la documentación vigente.
Ver: crear tool kits seleccionados sin confundirlos con seguridad
Un kit es un conjunto seleccionado de herramientas tomadas de los servidores registrados en el gateway. Su finalidad es el foco: un agente que gestiona reembolsos no tiene por qué ver una herramienta de calendario ni una de despliegue. Los kits pequeños también mejoran la calidad, porque LangChain señala que, cuando un agente tiene cientos o miles de herramientas, cargarlas todas a la vez aumenta la latencia y dificulta elegir la adecuada. Se permiten hasta 10,000 herramientas por kit, pero trata esa cifra como un techo y no como un objetivo.
Los kits no son control de acceso
El mismo llamante que usa un kit puede usar también kits/me/mcp, que ofrece todas las herramientas que ese llamante puede utilizar. Por eso la documentación de LangChain afirma claramente que un kit no es un control de acceso. Quitar una herramienta de un kit no impide una llamada que la identidad del agente tenga permitida. El control efectivo tiene que estar en Actuar como y en Permitir.
Mantén los kits actualizados
Tool Gateway guarda en caché la lista de herramientas de cada servidor durante dos horas, según la documentación de tool kits. Incluye la actualización de kits en cada versión de un servidor MCP, o asume que los agentes pueden ver una lista de herramientas con hasta dos horas de retraso tras un cambio. Esto importa sobre todo cuando una versión elimina una herramienta a la que ya no quieres que lleguen los agentes.
Actuar como: elegir la identidad para usuarios y agentes autónomos
La identidad determina qué permisos lleva una llamada a una herramienta. En nuestro esquema Ver / Actuar como / Permitir, es la capa que aborda los permisos excesivos. Antes de elegir un patrón, recomendamos leer la documentación de identidad junto con los dos enfoques siguientes.
Credenciales por usuario
Cada usuario conecta su propia cuenta mediante el flujo de inicio de sesión descrito arriba. Este enfoque encaja con asistentes que actúan en nombre de una persona, ya que el agente solo puede hacer lo que esa persona ya puede hacer en el sistema de origen.
Clave de servicio con la cabecera X-LangSmith-Identity
Los sistemas de backend usan una clave de servicio junto con una cabecera X-LangSmith-Identity. Tool Gateway confía en el valor de esa cabecera tal como llega. Por tanto, cualquier llamante que tenga la clave de servicio puede actuar como cualquier usuario. Envía la cabecera solo desde un backend que controles y no expongas nunca la clave de servicio a un navegador ni a un usuario final; así lo recomienda la propia LangChain. Trata esta clave como una credencial de máximo privilegio.
La comparación siguiente es una valoración nuestra, no documentación de LangChain.
| Pregunta | Credenciales por usuario | Clave de servicio en un backend |
|---|---|---|
| En nombre de quién actúa la llamada | Una persona que ha conectado su propia cuenta | La identidad que tu backend envíe en la cabecera |
| Uso típico | Asistentes interactivos y copilotos | Servicios de backend y agentes desatendidos o programados |
| Riesgo principal | Cuentas conectadas con más derechos de los que necesita la tarea | Una clave filtrada permite suplantar a cualquier usuario |
| Políticas de aprobación | Viables, porque la persona está presente para confirmar | Solo útiles si hay una persona presente; si no, usa políticas de bloqueo |
Nuestra regla práctica: usa credenciales por usuario cuando haya una persona presente y la acción sea suya, y la clave de servicio, enviada solo desde un backend que controles, cuando un trabajo se ejecute de forma desatendida o actúe en nombre del sistema.
Permitir: escribir políticas de bloqueo y aprobación que realmente funcionen
Las políticas son la capa de control efectivo, y dos comportamientos por defecto de la documentación de políticas condicionan todo lo demás. Una llamada que no coincide con ninguna política se ejecuta. Si una llamada coincide a la vez con una política de bloqueo y con una de aprobación, se bloquea. El primero es el que suele pillar desprevenida a la gente: una herramienta sin política es una herramienta que cualquier llamante autorizado puede usar.
Quién aprueba realmente
Con una política de aprobación, quien aprueba la llamada es el propio llamante, no un revisor aparte. Cada llamada se confirma antes de ejecutarse, pero no se envía nada a un administrador. Un agente que se ejecuta sin nadie presente no puede aprobar llamadas. Para ese caso, LangChain recomienda una política de bloqueo que impida al agente llamar a la herramienta.
El control con intervención humana, en el que una persona aprueba las acciones de alto impacto antes de que ocurran, figura entre las mitigaciones que recomienda OWASP. La aprobación por parte del llamante encaja cuando un usuario deja que un asistente envíe un correo desde su propia cuenta. No encaja con acciones que requieren una segunda mirada, como un reembolso por encima de un umbral fijado por tu equipo de finanzas. En esos casos, bloquea la herramienta en el gateway o crea un paso de aprobación previa en tu propia aplicación.
Capacidad
Una organización puede tener hasta 1,000 políticas que se aplican a todos los espacios de trabajo, más hasta 100 políticas por espacio de trabajo. Crear una política por encima de cualquiera de esos límites devuelve un error 422. Coloca a nivel de organización reglas como el bloqueo de herramientas irreversibles para agentes desatendidos, y en los espacios de trabajo las reglas específicas de cada equipo. Si generas políticas de forma automática, gestiona el error 422 para que el script falle de forma visible en lugar de dejar una regla sin crear.
Plan de despliegue: de secretos dispersos a un único gateway gobernado
Ejecuta estos pasos de menor a mayor riesgo.
- Inventario. Enumera todos los servidores MCP y herramientas que usan tus agentes y etiqueta cada uno según su impacto: lectura, escritura, irreversible o de cara al exterior.
- Registra los servidores. Traslada las credenciales de origen al gateway y después confirma que ninguna configuración de agente conserva una clave de origen.
- Ver. Crea un kit por cada rol de agente con el conjunto mínimo útil de herramientas.
- Actuar como. Credenciales por usuario para asistentes que actúan en nombre de personas; la clave de servicio, solo desde un backend, para trabajos autónomos.
- Permitir. Primero políticas de bloqueo, para agentes desatendidos y herramientas irreversibles, y después políticas de aprobación para llamadas interactivas sensibles.
- Confirma que llegan las trazas. Revisa el proyecto de trazas tool-gateway y la pestaña Usage tras tus primeras llamadas de prueba.
- Pruebas de carga. Prueba frente a los límites documentados (consulta Advertencias más abajo) con tráfico realista.
Lista de comprobación previa a producción
- [ ] No quedan claves ni tokens de origen en el código de los agentes, en los prompts ni en la configuración de los clientes
- [ ] Ningún agente desatendido depende de una política de aprobación
- [ ] Los clientes gestionan las respuestas de inicio de sesión HTTP 428 sin entrar en bucle
- [ ] Los agentes tratan la salida de las herramientas como entrada no fiable
- [ ] La actualización de kits forma parte del proceso de publicación de los servidores MCP
Observabilidad: qué registran las trazas y la pestaña Usage
Las trazas de llamadas a herramientas registran la herramienta, el servidor, el usuario, el resultado y la duración de cada llamada. Los datos enviados a la herramienta o devueltos por ella no se almacenan. Los contenidos sensibles quedan fuera del registro, y también el detalle que quizá quieras más adelante para una investigación. Las trazas van a un proyecto de trazas llamado tool-gateway, que el gateway crea al registrar la primera llamada, como explica la documentación de trazas. Las trazas del espacio de trabajo son gratuitas y no cuentan para tus límites de trazas, así que el coste no es motivo para prescindir de ellas. Para comprobaciones rápidas, la pestaña Usage muestra las 100 llamadas a herramientas más recientes de los últimos 7 días, con la herramienta, el servidor, el resultado, la latencia y la hora de inicio de cada una. Esa vista sirve para comprobaciones en directo durante el despliegue, no para auditorías a largo plazo.
Si tu proceso de cumplimiento normativo o de respuesta a incidentes necesita análisis forense a nivel de contenido, ese registro tiene que estar en la capa de tu agente o de tu aplicación, por ejemplo junto a las trazas GenAI de OpenTelemetry para agentes.
Advertencias, límites de la beta y cuándo siguen bastando los secretos por agente
Los límites estrictos que recoge la documentación de Tool Gateway de LangChain, empezando por la introducción How Tool Gateway works, son un tamaño de petición de 1 MB, un tamaño de respuesta de 8 MB, 60 segundos para que el servidor MCP empiece a responder y 100 peticiones por segundo con picos de hasta 1,000. Las herramientas que devuelven documentos grandes o dependen de sistemas de origen lentos son las primeras que conviene someter a pruebas de carga.
Durante la beta, el acceso se limita a los planes Plus y Enterprise y a las cuatro regiones de nube indicadas. El comportamiento de la beta puede cambiar, y esta guía refleja la documentación disponible en el lanzamiento. Recomendamos resolver los detalles de implementación señalados al principio, como los requisitos de transporte y qué planes incluyen las funciones de gobernanza, antes de planificar una migración.
Cuándo compensa un gateway
Un gateway compensa cuando tienes muchos servidores MCP y muchos agentes, cuando cada usuario necesita acceso delegado o cuando un equipo de seguridad quiere un único lugar para definir y revisar las políticas.
Cuándo pueden bastar los secretos por agente
No todos los equipos lo necesitan. Si ejecutas un solo agente con unas pocas herramientas, un único responsable y sin acceso delegado de usuarios, un gateway central puede añadir más proceso que protección.
Puntos clave
- LangSmith Tool Gateway entró en beta pública el 19 de noviembre de 2026, en los planes Plus y Enterprise, en GCP US, GCP EU, GCP APAC y AWS US. Azure US queda excluida.
- El modelo Ver / Actuar como / Permitir asocia las causas de la Agencia Excesiva de OWASP a los kits, la identidad y las políticas. Cada capa tiene sus propios límites.
- El llamante se autentica solo ante LangSmith y nunca tiene los tokens ni las claves de API de los servidores MCP de origen, en línea con la prohibición de reenviar tokens de la especificación MCP.
- Los tool kits determinan lo que ve un agente, pero no son control de acceso, porque un llamante puede seguir usando kits/me/mcp y todas las herramientas que su identidad permite.
- Con la cabecera X-LangSmith-Identity, cualquiera que tenga la clave de servicio puede actuar como cualquier usuario. Guarda esa clave en un backend que controles.
- Las políticas permiten las llamadas por defecto, el bloqueo prevalece sobre la aprobación y quien aprueba es el llamante. Los agentes desatendidos necesitan políticas de bloqueo.
- Las trazas no guardan el contenido de las llamadas y la salida de las herramientas llega sin cambios. Planifica en torno a los límites de 1 MB por petición, 8 MB por respuesta, 60 segundos y 100 peticiones por segundo.
Conclusión
Empieza por el inventario. Etiqueta cada herramienta MCP que usan tus agentes como lectura, escritura, irreversible o de cara al exterior, y escribe políticas de bloqueo para las irreversibles y las de cara al exterior antes de pasar cualquier agente al gateway. Después lleva un único rol de agente por todo el recorrido, con su propio kit pequeño y el modo de identidad que corresponda a quién está realmente presente. Amplía el despliegue solo cuando sus llamadas aparezcan en el proyecto de trazas tool-gateway y las pruebas de carga se mantengan dentro de los límites documentados.
La excepción es el equipo pequeño. Si ejecutas un solo agente con unas pocas herramientas y un único responsable, un secreto en el servidor con un alcance limitado y tokens de corta duración puede seguir siendo la opción más sencilla. El gateway puede esperar hasta que llegue un segundo agente o el acceso delegado de usuarios.
Preguntas frecuentes
¿Está LangSmith Tool Gateway disponible de forma general y qué planes y regiones lo admiten?
Todavía no. Se lanzó en beta pública el 19 de noviembre de 2026. La beta está disponible en los planes Plus y Enterprise de LangSmith y, en LangSmith Cloud, cubre GCP US, GCP EU, GCP APAC y AWS US. Azure US queda excluida. Consulta la documentación vigente antes de comprometerte, ya que el alcance de la beta puede cambiar.
¿Impiden los tool kits que un agente llame a herramientas que no están en el kit?
No. La documentación de LangChain indica que un kit no es un control de acceso, porque el mismo llamante puede usar kits/me/mcp, que ofrece todas las herramientas que ese llamante puede utilizar. Los kits determinan lo que ve el agente. Para restringir lo que puede hacer de verdad, apóyate en el alcance de la identidad y en las políticas de bloqueo.
¿Qué debe hacer mi cliente cuando recibe un HTTP 428?
Tratarlo como un paso de inicio de sesión. La respuesta 428 incluye un enlace de inicio de sesión para un usuario que no ha conectado su cuenta. Muestra el enlace, espera a que el usuario confirme el inicio de sesión y reintenta la llamada original una sola vez. Para saber qué campo contiene el enlace, consulta la documentación vigente o examina una respuesta real durante las pruebas.
¿Quién aprueba una llamada bajo una política de aprobación y qué debo hacer con los agentes desatendidos?
Quien aprueba la llamada es el llamante. No hay un revisor aparte ni una cola de administración. Un agente que se ejecuta sin nadie presente no puede aprobar llamadas, así que LangChain recomienda políticas de bloqueo para impedir que esos agentes usen una herramienta. Si necesitas que una segunda persona revise las acciones de alto impacto, incorpora ese paso en tu propia aplicación o bloquea la herramienta.
¿Almacena Tool Gateway las entradas y salidas de las llamadas a herramientas?
No. Las trazas de llamadas a herramientas registran la herramienta, el servidor, el usuario, el resultado y la duración de cada llamada, pero los datos enviados a la herramienta o devueltos por ella no se almacenan. Si necesitas registros a nivel de contenido para cumplimiento normativo o análisis forense, planifica ese registro en la capa de tu propia aplicación.
¿Limpia el gateway las respuestas de las herramientas frente a la inyección de prompts?
No. Tool Gateway entrega al llamante la respuesta de cada servidor sin cambios, y la documentación aconseja tratar la salida de las herramientas como una entrada no fiable para tu agente. Las defensas contra la inyección de prompts siguen formando parte del diseño de tu agente.
¿Cuáles son los límites documentados de tamaño, tiempo de espera y frecuencia?
Los límites estrictos documentados son un tamaño de petición de 1 MB, un tamaño de respuesta de 8 MB, 60 segundos para que el servidor MCP empiece a responder y 100 peticiones por segundo con picos de hasta 1,000. Somete a pruebas de carga las herramientas que devuelven documentos grandes o dependen de sistemas de origen lentos antes de pasar a producción.
Fuentes
- https://www.langchain.com/blog/langsmith-tool-gateway
- https://docs.langchain.com/langsmith/tool-gateway-how-it-works
- https://docs.langchain.com/langsmith/tool-gateway-quickstart
- https://docs.langchain.com/langsmith/tool-gateway-tool-kits
- https://docs.langchain.com/langsmith/tool-gateway-identity
- https://docs.langchain.com/langsmith/tool-gateway-policies
- https://docs.langchain.com/langsmith/tool-gateway-traces
- https://www.unite.ai/langchain-launches-langsmith-tool-gateway-to-govern-agent-tool-calls/
- https://superpowerdaily.com/posts/langchain-launches-a-gateway-to-control-which-tools-ai-agents-can-use
- https://modelcontextprotocol.io/specification/2025-03-26/basic/transports
- https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations
- https://genai.owasp.org/llmrisk/llm062025-excessive-agency/



