Construir servidores MCP

Guía avanzada para desarrolladores que construyen su propio servidor MCP autenticado contra Whatalo con OAuth 2.1.

Esta es una guía avanzada para desarrolladores que construyen su propio servidor MCP (Model Context Protocol) autenticado contra la API de Whatalo en nombre de un comerciante.

La mayoría de los integradores no necesitan esto. Si quieres conectar una herramienta de IA a una tienda Whatalo, usa el servidor MCP de Whatalo que ya existe — consulta Conectar tu tienda a herramientas de IA. Esta página es solo para desarrolladores que construyen un servidor MCP nuevo propio.

Audiencia: autores de servidores MCP y desarrolladores que construyen resource servers basados en OAuth para Whatalo.

Arquitectura

Toda integración MCP + Whatalo tiene tres actores:

Rol	Quién	Identificador
Authorization Server	Whatalo	`app.whatalo.com`
Resource Server	Tu servidor MCP	Recibe tokens Bearer, los valida por introspección
OAuth Client	La aplicación host MCP	Obtiene un `client_id` vía Dynamic Client Registration

┌─────────────────────┐     ┌──────────────────────┐     ┌───────────────────┐
│   App Host MCP      │     │  Auth Server Whatalo  │     │  Tu Servidor MCP  │
│   (OAuth Client)    │     │  (app.whatalo.com)    │     │  (Resource Server)│
└──────────┬──────────┘     └──────────┬────────────┘     └─────────┬─────────┘
           │                           │                             │
           │  1. DCR: POST /oauth/register                          │
           ├──────────────────────────►│                             │
           │  ◄── client_id ───────────│                             │
           │                           │                             │
           │  2. Authorization Code + PKCE                          │
           ├──────────────────────────►│                             │
           │  ◄── access + refresh ────│                             │
           │                           │                             │
           │  3. Petición MCP con token Bearer                       │
           ├─────────────────────────────────────────────────────►  │
           │                           │  4. Introspección del token │
           │                           │◄────────────────────────────┤
           │                           ├──── { active, sub, scope } ►│
           │  ◄── Respuesta MCP ─────────────────────────────────────┤

Punto clave: tu servidor MCP es un Resource Server, no un OAuth client. La aplicación host MCP que corre en la máquina del usuario es el OAuth client. Este es el error más común al combinar MCP y OAuth — no registres tu servidor como el cliente.

Flujo OAuth — reutiliza la referencia canónica

Tu servidor MCP usa los endpoints estándar de OAuth 2.1 de Whatalo. Cada paso está documentado una sola vez, en la sección OAuth — sigue esas páginas en lugar de una copia duplicada:

Paso	Referencia
Metadata del Authorization Server	Discovery
Dynamic Client Registration	Registration
Authorization Code + PKCE	Authorization Flow
Intercambiar el código por tokens	Token Endpoint
Refrescar tokens	Token Exchange
Validar tokens Bearer	Introspection
Revocar tokens	Revocation
Scopes disponibles	Scopes
Formato de errores	Errors

Resource Server discovery

Tu servidor MCP debe publicar metadata OAuth Protected Resource (RFC 9728) para que las aplicaciones host MCP descubran a Whatalo como authorization server:

GET https://TU_DOMINIO_MCP/.well-known/oauth-protected-resource

Respuesta:

{
  "resource": "https://TU_DOMINIO_MCP",
  "authorization_servers": ["https://app.whatalo.com"],
  "scopes_supported": [
    "read:store",
    "read:products",
    "write:products",
    "read:inventory",
    "write:inventory",
    "read:categories",
    "write:categories",
    "read:customers",
    "read:orders",
    "write:orders"
  ],
  "bearer_methods_supported": ["header"]
}

El array authorization_servers apuntando a https://app.whatalo.com es lo que vincula tu servidor MCP con Whatalo como authorization server. Anuncia solo los scopes que tu servidor realmente aplica.

Enrutar peticiones a la tienda correcta

Cuando validas un token Bearer entrante por introspección, la respuesta del token activo incluye un campo whatalo_store_id:

{
  "active": true,
  "scope": "read:products read:orders",
  "sub": "usr_7f3a9b2c1d4e5f6a",
  "whatalo_store_id": "str_8k2m4n6p"
}

El campo whatalo_store_id contiene el ID público corto de la tienda — el mismo que se usa en las URLs de Whatalo. Úsalo para enrutar operaciones al contexto de la tienda correcta en tu servidor MCP multitenant. Un comerciante con varias tiendas autoriza cada tienda por separado, así que cada token resuelve a exactamente una tienda.

Checklist de seguridad

✅ Usa siempre PKCE con S256 — nunca plain
✅ Valida el parámetro state en cada callback
✅ Guarda los tokens en el keychain del sistema o en almacenamiento cifrado — nunca en localStorage
✅ Cachea las respuestas de introspección con active: true por máximo 60 segundos — las revocaciones son inmediatas
✅ Solicita solo los scopes mínimos que necesitas
❌ Nunca registres tokens en texto plano ni los envíes en query strings de la URL

Referencias

RFC 9728 — OAuth Protected Resource Metadata
RFC 7662 — Token Introspection
MCP Authorization Specification — Model Context Protocol