AgentAuth

Auth0, pero para agentes. Servicio de identidad y autenticación para agentes de IA.

Documentación

AgentAuth

Servicio de identidad y autenticación para agentes de IA. Emite credenciales verificables, gestiona el ciclo de vida de las claves API y proporciona flujos similares a OAuth para interacciones máquina a máquina.

Servidor MCP

AgentAuth está disponible como servidor MCP (Protocolo de Contexto de Modelo) — no se requiere código de cliente HTTP. Cualquier agente compatible con MCP puede autenticarse y gestionar permisos mediante llamadas a herramientas estándar.

El endpoint MCP está integrado en la API de AgentAuth en /mcp. No se necesita instalación adicional.

Configuración

Alojado (recomendado)

Añade esto a la configuración de tu cliente MCP y listo:

{
  "mcpServers": {
    "agentauth": {
      "url": "https://agentauth.radi.pro/mcp"
    }
  }
}

Ubicaciones de configuración específicas por cliente

Cliente	Archivo de configuración
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Claude Code (proyecto)	`.claude/settings.json`
Claude Code (global)	`~/.claude/settings.json`
Cursor (global)	`~/.cursor/mcp.json`
Cursor (proyecto)	`.cursor/mcp.json`
VS Code / Copilot	`settings.json` de usuario o espacio de trabajo bajo `github.copilot.chat.mcpServers`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Continue.dev	`~/.continue/config.json`
Zed	`~/.config/zed/settings.json` bajo `context_servers`

Todos usan la misma URL: https://agentauth.radi.pro/mcp

Modo local / stdio

Para entornos de desarrollo o aislados:

cd mcp-server
uv pip install -e .

{
  "mcpServers": {
    "agentauth": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/agent-auth/mcp-server", "agentauth-mcp"],
      "env": {
        "AGENTAUTH_URL": "https://agentauth.radi.pro"
      }
    }
  }
}

Autoalojamiento

Si ejecutas tu propia instancia de AgentAuth, el endpoint MCP está disponible automáticamente en /mcp. Establece AGENTAUTH_URL a tu instancia:

AGENTAUTH_URL=https://your-agentauth-instance.com

Variables de Entorno

Variable	Requerida	Descripción
`AGENTAUTH_URL`	Sí (modo stdio)	URL base del servicio AgentAuth
`AGENTAUTH_API_KEY`	No	Clave API predeterminada utilizada por `authenticate` cuando no se pasa ninguna

Al usar el endpoint /mcp alojado directamente, no se necesitan variables de entorno en el cliente.

Flujo de Uso Típico

1. quickstart          → register agent + get API key + access token (first run only)
2. authenticate        → exchange saved API key for a fresh access token
3. [do work]           → pass access_token to list_agents, create_delegation, check_permission, etc.
4. refresh_token       → get a new token pair before the access token expires
5. revoke_token        → invalidate tokens when done (optional)

Herramientas Disponibles

`discover`

Obtén las capacidades y endpoints del servidor AgentAuth.

Devuelve los tipos de concesión admitidos, alcances disponibles, tiempos de vida de tokens y todas las URLs de endpoints. Llama a esta herramienta primero para entender qué ofrece el servicio.

discover()

`quickstart`

Registra un nuevo agente raíz y obtén credenciales en una sola llamada. La forma más rápida de comenzar.

Devuelve la identidad del agente, clave API (mostrada una vez — guárdala inmediatamente), token de acceso, token de actualización y marcas de tiempo de expiración.

Parámetro	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre legible del agente, p. ej. `"my-data-pipeline"`
`agent_type`	string	Sí	Uno de: `orchestrator`, `autonomous`, `assistant`, `tool`
`description`	string	No	Propósito del agente

quickstart(
  name="my-pipeline",
  agent_type="autonomous",
  description="Processes nightly ETL jobs"
)

La respuesta incluye:

agent — identidad registrada (id, nombre, tipo de agente, nivel de confianza, …)
api_key — clave API sin procesar, guárdala ahora
access_token — token Bearer listo para usar (válido 15 min)
refresh_token — úsalo antes de que expire el token de acceso
expires_at / refresh_before — marcas de tiempo ISO-8601

`authenticate`

Intercambia una clave API por un token de acceso (concesión client_credentials).

Parámetro	Tipo	Requerido	Descripción
`api_key`	string	No	Clave API de AgentAuth. Recurre a la variable de entorno `AGENTAUTH_API_KEY`
`scopes`	string[]	No	Alcances a solicitar. Por defecto, todos los alcances que la credencial permite

authenticate(
  api_key="ak_live_...",
  scopes=["api.read", "agents.write"]
)

Devuelve: access_token, refresh_token, token_type, expires_in, expires_at, refresh_before

`refresh_token`

Intercambia un token de actualización por un nuevo par de tokens de acceso + actualización.

Úsalo cuando el token de acceso esté cerca de expirar — consulta refresh_before de la respuesta de authenticate.

Parámetro	Tipo	Requerido	Descripción
`refresh_token_value`	string	Sí	Token de actualización de una llamada anterior a `authenticate` o `quickstart`

refresh_token(refresh_token_value="rt_...")

`introspect_token`

Comprueba si un token es válido e inspecciona sus reclamaciones (RFC 7662).

Devuelve active: true/false más las reclamaciones decodificadas (alcances, tipo de agente, nivel de confianza, expiración) si está activo.

Parámetro	Tipo	Requerido	Descripción
`token`	string	Sí	El token de acceso o actualización a inspeccionar

introspect_token(token="eyJ...")

`revoke_token`

Revoca un token de acceso o actualización inmediatamente (RFC 7009).

El token se añade a la lista de bloqueo y se invalida. Idempotente — revocar un token ya revocado tiene éxito.

Parámetro	Tipo	Requerido	Descripción
`token`	string	Sí	Token a revocar

revoke_token(token="eyJ...")

`create_credential`

Emite una nueva clave API para un agente.

El raw_key se devuelve una vez — guárdalo inmediatamente. Las lecturas posteriores solo muestran el prefijo de la clave.

Parámetro	Tipo	Requerido	Descripción
`agent_id`	string	Sí	UUID del agente
`access_token`	string	Sí	Token Bearer
`scopes`	string[]	No	Restricciones de alcance opcionales para la nueva clave

create_credential(
  agent_id="01927...",
  access_token="eyJ...",
  scopes=["api.read"]
)

`rotate_credential`

Revoca una clave API existente y emite un reemplazo en una sola operación atómica.

Devuelve nuevos campos de credencial, el nuevo raw_key (guárdalo) y el antiguo credential_id.

Parámetro	Tipo	Requerido	Descripción
`credential_id`	string	Sí	UUID de la credencial a rotar
`access_token`	string	Sí	Token Bearer

rotate_credential(
  credential_id="01928...",
  access_token="eyJ..."
)

`revoke_credential`

Revoca permanentemente una clave API. Irreversible.

Parámetro	Tipo	Requerido	Descripción
`credential_id`	string	Sí	UUID de la credencial a revocar
`access_token`	string	Sí	Token Bearer

revoke_credential(
  credential_id="01928...",
  access_token="eyJ..."
)

`create_delegation`

Delega un subconjunto de tus permisos a otro agente.

El delegado solo puede recibir alcances que el delegador ya posee. Las delegaciones pueden encadenarse hasta max_chain_depth veces.

Parámetro	Tipo	Requerido	Descripción
`delegate_agent_id`	string	Sí	UUID del agente que recibe los permisos
`scopes`	string[]	Sí	Alcances a delegar (deben ser un subconjunto de los tuyos)
`access_token`	string	Sí	Token Bearer del agente delegador
`max_chain_depth`	int	No	Cuántas veces el delegado puede re-delegar (predeterminado: 3)
`expires_in_hours`	int	No	Expiración de la delegación en horas desde ahora

create_delegation(
  delegate_agent_id="01929...",
  scopes=["api.read", "agents.read"],
  access_token="eyJ...",
  max_chain_depth=1,
  expires_in_hours=24
)

`check_permission`

Evaluación de políticas en modo simulación — comprueba si un agente tiene permitido realizar una acción sin aplicarla realmente. Útil para verificaciones previas.

Parámetro	Tipo	Requerido	Descripción
`agent_id`	string	Sí	UUID del agente a verificar
`action`	string	Sí	Uno de: `read`, `write`, `delete`, `execute`, `delegate`, `admin`
`resource`	string	Sí	Ruta del recurso, p. ej. `"/api/v1/credentials"`
`access_token`	string	Sí	Token Bearer

check_permission(
  agent_id="01927...",
  action="write",
  resource="/api/v1/credentials",
  access_token="eyJ..."
)

Devuelve: allowed: true/false, detalles de la política coincidente, razonamiento de la decisión.

`list_agents`

Lista agentes registrados con paginación.

Parámetro	Tipo	Requerido	Descripción
`access_token`	string	Sí	Token Bearer
`limit`	int	No	Máximo de resultados, 1–100 (predeterminado: 50)
`offset`	int	No	Desplazamiento de paginación (predeterminado: 0)

list_agents(access_token="eyJ...", limit=10, offset=0)

`get_agent`

Obtén detalles completos de un agente específico.

Devuelve los campos del agente (id, nombre, tipo de agente, nivel de confianza, estado) combinados con metadatos (is_root, is_active).

Parámetro	Tipo	Requerido	Descripción
`agent_id`	string	Sí	UUID del agente
`access_token`	string	Sí	Token Bearer

get_agent(agent_id="01927...", access_token="eyJ...")

Tipos de Agente

Tipo	Descripción
`orchestrator`	Coordina otros agentes; alta confianza
`autonomous`	Agentes autodirigidos que ejecutan tareas largas
`assistant`	Agentes interactivos que responden a solicitudes de usuarios
`tool`	Agentes utilitarios de propósito específico

Tiempos de Vida de Tokens

Token	Tiempo de vida predeterminado
Token de acceso	15 minutos
Token de actualización	7 días
Claves API	Configurable (sin expiración predeterminada)

Ejemplo de SDK de Python

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client("https://agentauth.radi.pro/mcp") as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # Register and get credentials
        result = await session.call_tool("quickstart", {
            "name": "my-agent",
            "agent_type": "autonomous",
        })
        api_key = result.content[0].text  # save this

        # Authenticate on subsequent runs
        auth = await session.call_tool("authenticate", {"api_key": api_key})
        token = auth.content[0].text  # access_token

API REST

El servidor MCP envuelve la API REST de AgentAuth. La documentación interactiva de la API está disponible en:

https://agentauth.radi.pro/docs