El servidor MCP

Weblabor Base trae dos servidores MCP, donde una persona conecta su propio asistente de IA —Claude, ChatGPT o cualquier cliente que hable MCP por HTTP— con un token:

• El servidor del usuario, en /mcp, con las herramientas del área del usuario: los tickets, los archivos propios de la persona y sus referidos. Sus tokens se crean en Mi perfil.
• El servidor de administración, en /mcp/admin, con las herramientas del panel de administración: usuarios y roles, bloqueo, anuncios, el registro de actividad y las cifras del producto. Solo llegan los superadministradores, y sus tokens se crean en la pantalla MCP del panel de administración.

Un token abre solo el servidor para el que se creó. Todo lo que el asistente hace por ahí lo hace como la persona que creó el token, con sus permisos y en su idioma. Esta guía cubre cómo encender cada servidor, qué hacen las herramientas de la base, los límites y cómo agregar las herramientas propias de tu producto.

Si un asistente estaba conectado a /mcp antes de que existiera el servidor de administración, las herramientas de administración ya no están ahí: se movieron a /mcp/admin, con un token de administración. Los tokens creados antes siguen funcionando en /mcp.

Enciende el servidor del usuario para una cuenta

MCP es un complemento llamado MCP, sin precio. Los seeders lo crean en el primer deploy (AddOnSeeder), y cada cuenta empieza con él apagado, como todo complemento:

• Sin complementos de pago (FEATURE_ADDONS_ENABLED apagado, como viene Weblabor Base), aparece en Complementos con su interruptor Activar.
• Con los complementos de pago encendidos, es un complemento gratuito del catálogo que la cuenta activa.

Apagarlo detiene todos los tokens de esa cuenta a la vez, sin borrarlos, y encenderlo de nuevo los devuelve.

La pantalla de tokens también pide un permiso, Administrar tokens MCP (manage mcp tokens). El rol de administrador lo tiene; dáselo a cualquier otro rol desde Roles en el panel de administración. Una persona con el complemento encendido y el permiso ve Asistente de IA (MCP) en Mi perfil, donde:

1. Copia la URL del servidor MCP en su asistente.
2. Escribe un Nombre del token, como el asistente para el que es, y hace clic en Crear token.
3. Copia el token del recuadro amarillo. Se muestra una sola vez; después de Hecho solo queda su nombre.
4. Hace clic en Revocar junto a un token para detenerlo de inmediato. Los demás siguen funcionando.

El asistente manda el token como Authorization: Bearer <token> en cada petición.

Un producto puede dejar apagado el servidor del usuario para todos con app_server (ver Cambia la configuración): la dirección se queda y contesta que el servidor está apagado.

Enciende el servidor de administración

El servidor de administración es para los superadministradores —los correos de config('app.sudo')— y no tiene complemento ni precio. Un superadministrador abre MCP en el menú del panel de administración, que nadie más ve, donde:

1. Marca Servidor MCP de administración encendido. Empieza encendido: sin un token nadie entra.
2. Copia la URL del servidor MCP, la dirección /mcp/admin, en su asistente.
3. Crea, copia y revoca sus tokens de administración igual que en el perfil.

Apagado, todo token de administración se rechaza con Este servidor MCP está apagado.; la entrada del menú y los tokens se quedan, y encenderlo de nuevo los devuelve. Una persona que deja de ser superadministrador, o a la que se bloquea, se lleva sus tokens de administración.

Qué puede hacer el asistente

Las herramientas de administración de usuarios están en el servidor de administración, con las reglas del panel de administración. El panel de administración solo se abre con el rol de administrador, así que toda herramienta que llega a una de sus pantallas pide ese rol además del permiso:

Además de los usuarios, la base trae las herramientas de sus propias pantallas, cada una en el servidor de su pantalla y con las reglas de esa pantalla. Los tickets se quedan en el servidor del usuario incluso para la bandeja de soporte, porque quien atiende soporte la trabaja sin el rol de administrador:

Las herramientas de archivos solo llegan a la biblioteca propia de la persona, nunca a los archivos de otra cuenta, y ninguna sube archivos. Toda herramienta que elimina o cierra algo no cambia nada hasta que se vuelve a llamar con confirm: true.

Algunas herramientas dependen de un módulo: las de tickets existen mientras los tickets están encendidos (features.tickets.enabled), las de anuncios mientras los anuncios lo están (features.announcements) y las de referidos mientras los referidos lo están (features.referrals.enabled). Con el módulo apagado no se listan ni se pueden llamar, como sus pantallas contestan no encontrado. Una herramienta de un servidor llamada en el otro tampoco se encuentra.

Pregunta cómo va el producto

El servidor de administración también da las cifras del dashboard de administración, para preguntarle al asistente cómo va el producto sin abrir el panel. Solo un superadministrador llega a ellas, y a uno sin el rol de administrador que pide el dashboard le contestan que le falta ese rol. Solo leen y nunca dan un correo: las listas traen el ID, el nombre, la fecha de registro y la última conexión de cada usuario, y lo demás son conteos.

Las cifras son las del dashboard para el mismo rango: por omisión los últimos 30 días, por día hasta 50 días y después por semana o por mes, y un rango abarca hasta 366 días. Los días son días completos en la zona horaria de la aplicación para todos, así que un registro de las primeras horas de un día cuenta en ese día, sea cual sea la zona horaria de quien pregunta. Los usuarios conectados por día salen de la estadística que se guarda cada noche del día anterior, como en el dashboard, y la respuesta dice cuántos días del rango aún no la tienen. El resumen y las listas de usuarios activos e inactivos leen en cambio la última conexión de cada persona, y cada respuesta dice de qué fuente leyó. Activos e inactivos comparten un solo límite, el inicio del día de hace ese número de días, así que nadie sale en las dos listas. Consultar no deja nada en el registro de actividad, así que nunca cambia los eventos del registro de actividad del dashboard ni los que contesta daily-activity.

Cuando la persona no tiene permiso, la herramienta contesta con el permiso que falta, por ejemplo la persona que creó este token necesita el permiso «retrieve user», o con el rol, la persona que creó este token necesita el rol admin, y no cambia nada. Un token nunca llega más lejos que su creador.

Lo que cambia una herramienta queda en el registro de actividad con el creador como autor, y el historial del registro muestra una etiqueta Vía MCP con el nombre del token.

Cuándo el servidor dice que no

El servidor rechaza antes de ejecutar nada, en el idioma del creador:

Cambia la configuración

Vive bajo mcp en config/features.php, sin variable de entorno:

'mcp' => [
    'app_server' => true,
    'token_prefix' => 'mcp_',
    'requests_per_minute' => 600,
],

app_server en false deja apagado el servidor del usuario para todo el producto, sin quitar su dirección: cada petición contesta que el servidor está apagado. El servidor de administración no lo lee; tiene su interruptor en el panel de administración.

token_prefix solo nombra al producto al principio de cada token nuevo. Un token se encuentra por el hash SHA-256 de su valor completo, así que cambiar el prefijo nunca detiene los tokens creados antes. Solo se guarda ese hash, en mcp_tokens.

Agrega las herramientas de tu producto

Escribe una clase en app/Mcp/Tools que extienda App\Mcp\Tools\ApplicationTool, pregunta en ella los permisos del creador y regístrala desde un service provider en el servidor de su pantalla —AppServer para una pantalla del área del usuario, AdminServer para una del panel de administración—:

use App\Mcp\Servers\AppServer;

public function boot(): void
{
    AppServer::registerTools([
        \App\Mcp\Tools\ListInvoices::class,
    ]);
}

namespace App\Mcp\Tools;

use App\Models\Invoice;
use Laravel\Mcp\{Request, Response, ResponseFactory};
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;

#[Description('Lists the invoices the person can see.')]

#[IsReadOnly]
class ListInvoices extends ApplicationTool
{
    public function handle(Request $request): Response|ResponseFactory
    {
        if (! $this->token()->allows('viewAny', Invoice::class)) {
            return $this->missingPermission('retrieve invoice');
        }
        return Response::structured([
            'invoices' => Invoice::latest()->limit(25)->get(['id', 'number', 'total'])->toArray(),
        ]);
    }
}

El servidor la publica junto a las herramientas de la base, con el nombre de la clase en kebab case (list-invoices), y el otro servidor nunca. La base nunca necesita editarse para ello, y la base registra las herramientas de sus propias pantallas de la misma forma, así que un producto solo agrega a la lista de cada servidor. Un servidor propio del producto que extiende AppServer conserva las herramientas registradas en AppServer además de las suyas.

Dos ajustes de ApplicationTool cubren los casos que usan las herramientas de la base. Pon protected bool $superadminOnly = true; y empieza handle() con if (! $this->isListedFor($this->creator())) { return $this->onlyForSuperadmins(); } para una herramienta que solo ven los superadministradores. Una herramienta que llega a una pantalla del panel de administración también comprueba $this->creator()->isAdmin() y contesta $this->missingAdminRole() sin él. Sobrescribe moduleIsOn() para que devuelva el interruptor de tu módulo en una herramienta que debe desaparecer mientras ese módulo está apagado. Una herramienta que elimina contesta $this->confirmationRequired() hasta que recibe confirm: true. La referencia completa, con el middleware y las migraciones, está en docs/weblabor-base/mcp.md.