Descubrimiento del servidor

Los endpoints de descubrimiento permiten que tu cliente se configure solo: en lugar de escribir a mano cada URL, la lee de un documento estándar. Las bibliotecas OpenID Connect (Auth.js, Authlib, oidc-client-ts) solo necesitan el emisor, https://os.utilia.ai, y los clientes MCP llegan por aquí al servidor de autorización. Todos son públicos: no envíes X-Api-Key ni Authorization.

Viven en la raíz del dominio, fuera de /api, porque así lo exigen las especificaciones: https://os.utilia.ai/.well-known/....

Así los encadena un cliente MCP que solo conoce la dirección del servidor, por ejemplo https://os.utilia.ai/api/mcp/crm:

El paso de autorización está contado en Flujo de autorización.

Metadatos del servidor de autorización (RFC 8414)

Devuelve las direcciones de autorización, token, registro, revocación e introspección y lo que admite el servidor. En el ejemplo, scopes_supported está recortado: la respuesta real trae el catálogo entero de scopes, incluidos los conjuntos (crm:read, finance:full...).

{
  "issuer": "https://os.utilia.ai",
  "authorization_endpoint": "https://os.utilia.ai/api/oauth/authorize",
  "token_endpoint": "https://os.utilia.ai/api/oauth/token",
  "registration_endpoint": "https://os.utilia.ai/api/oauth/register",
  "revocation_endpoint": "https://os.utilia.ai/api/oauth/revoke",
  "introspection_endpoint": "https://os.utilia.ai/api/oauth/introspect",
  "scopes_supported": ["openid", "profile", "email", "crm:clients:view", "dev:projects:view", "..."],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "code_challenge_methods_supported": ["S256"],
  "prompt_values_supported": ["none", "login", "select_account", "consent"],
  "service_documentation": "https://os.utilia.ai/dashboard/docs/developers/mcp",
  "logo_uri": "https://os.utilia.ai/icons/icon-192x192.png",
  "service_name": "UTILIA OS"
}

Configuración de OpenID Connect

Es el documento anterior con los campos de OpenID Connect añadidos:

jwks_uristringobligatorio

https://os.utilia.ai/api/oauth/jwks: claves públicas para verificar el id_token.

userinfo_endpointstringobligatorio

https://os.utilia.ai/api/oauth/userinfo

end_session_endpointstringobligatorio

https://os.utilia.ai/api/oauth/logout: cierre de sesión iniciado por tu aplicación.

id_token_signing_alg_values_supportedstring[]obligatorio

RS256.

subject_types_supportedstring[]obligatorio

public.

claims_supportedstring[]obligatorio

sub, iss, aud, exp, iat, name, given_name, family_name, picture, email, email_verified, at_hash y nonce.

Lee jwks_uri de aquí en lugar de escribirlo en tu código: así un cambio de claves no te obliga a tocar nada.

Metadatos de cada recurso protegido (RFC 9728)

Cada servidor MCP de UTILIA OS es un recurso protegido con su propia lista de scopes. Los clientes MCP leen estos documentos para saber qué pedir.

Con ?resource= y la dirección de un servidor MCP devuelve los metadatos de ese servidor. Sin el parámetro, o con una dirección que no es de ningún servidor, devuelve los generales, con el recurso histórico /api/mcp y el catálogo entero.

{
  "resource": "https://os.utilia.ai/api/mcp/crm",
  "authorization_servers": ["https://os.utilia.ai"],
  "scopes_supported": ["crm:clients:view", "crm:leads:view", "support:tickets:view", "dev:calendar:view", "org:plan:view", "..."],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://os.utilia.ai/dashboard/docs/developers/mcp",
  "logo_uri": "https://os.utilia.ai/icons/icon-192x192.png",
  "resource_name": "UTILIA OS - CRM"
}

Cada servidor tiene además un atajo con el mismo documento:

Todos anuncian además los transversales que su servidor necesita: el plan contratado (org:plan:*), los avisos (org:notifications:*) y, salvo CRM y Proyectos, que ya los incluyen, los tres de tickets propios (support:tickets:view, create y update).

Dos casos en los que el documento anuncia menos de lo que podría pedirse, a propósito:

• Chat no anuncia chat:messages:send, chat:events:subscribe ni chat:agents:manage:external, ni los conjuntos chat:write y chat:full, que los incluyen: el servidor MCP de chat lee y organiza canales, pero no escribe mensajes. Publicar mensajes es cosa de la API externa (/api/external/v1/chat) con X-Api-Key.
• Marketing no anuncia ningún finance:*. Por eso sus operaciones de negocio originado por campaña devuelven recuentos, pero no importes. Lo explica Servidor MCP Marketing.

/api/mcp/work es la dirección pública del servidor de Proyectos; los tokens guardan como destinatario /api/mcp/dev, así que un mismo token sirve para las dos direcciones.

Otros documentos

Devuelve las mismas claves que GET /api/oauth/jwks. Solo lo necesitas si verificas tú la firma del id_token.

Devuelve lo mismo que /.well-known/oauth-protected-resource sin parámetro y existe solo para clientes antiguos. En una integración nueva, usa oauth-protected-resource con resource.

Ejemplos

# Servidor de autorización
curl -s 'https://os.utilia.ai/.well-known/oauth-authorization-server' | jq .
 
# OpenID Connect
curl -s 'https://os.utilia.ai/.well-known/openid-configuration' | jq .
 
# Recurso protegido del servidor de CRM
curl -s 'https://os.utilia.ai/.well-known/oauth-protected-resource?resource=https://os.utilia.ai/api/mcp/crm' | jq .
 
# Atajo del servidor de Finanzas
curl -s 'https://os.utilia.ai/.well-known/mcp-finance.json' | jq .

Estos documentos admiten hasta 600 peticiones por minuto y dirección IP. Aun así, guárdalos en caché en tu cliente: cambian muy poco.

Siguiente paso: Flujo de autorización.