Cómo funciona el servidor MCP de Guida

20 de enero de 2025 · 8 min de lectura ·

technical

Guida incluye un servidor Model Context Protocol (MCP) integrado. Es lo que permite que una IA externa, como Claude Code, Cursor o cualquier cliente compatible con MCP, controle el navegador. Es el puente entre decirle a una IA “quiero extraer datos de esta página” y las consultas DOM, clics y operaciones de almacenamiento reales que lo hacen posible.

Este artículo es un análisis técnico de su funcionamiento. Cubriremos el protocolo, la capa de transporte, cómo se registran las herramientas y el modelo de seguridad en tres capas que garantiza que la IA no pueda hacer nada sin su conocimiento y consentimiento.

Qué es MCP, brevemente

MCP es un protocolo JSON-RPC para conectar modelos de IA con herramientas externas. La IA envía una solicitud como “llama a la herramienta Navigate con url: https://example.com”, el servidor la ejecuta y devuelve el resultado. El modelo nunca toca el navegador directamente; solo ve el contrato de entrada/salida de la herramienta.

El protocolo define tres primitivas:

Tools - funciones que la IA puede llamar: navegar, hacer clic, extraer, etc.
Resources - datos que la IA puede leer: pestañas abiertas, contenido de página
Prompts - plantillas reutilizables para operaciones comunes

Guida implementa las primitivas de herramientas y recursos. Expone más de 100 herramientas que cubren automatización del navegador, almacenamiento de datos, búsqueda y más.

Transporte: HTTP local

MCP soporta varios transportes. Guida usa transporte HTTP local: el servidor ejecuta una instancia Kestrel integrada en http://127.0.0.1:9315.

La elección de HTTP en lugar de stdio tiene razones prácticas: Guida es una aplicación de escritorio WPF, no una herramienta CLI. No hay stdin/stdout al que conectar tuberías. HTTP también permite que clientes MCP externos se conecten mientras la interfaz del navegador, el estado de autorizaciones, el historial de tareas y los paneles del espacio de trabajo siguen visibles.

Para clientes HTTP streamable actuales, el endpoint útil es la raíz del servidor:

http://127.0.0.1:9315/

El handshake sigue el estándar MCP: el cliente inicializa, el servidor devuelve las capacidades disponibles, y después el cliente descubre herramientas y empieza a hacer llamadas.

Client → initialize
         {"jsonrpc": "2.0", "method": "initialize", ...}

Server → capabilities
         {"jsonrpc": "2.0", "id": 1, "result": {...}}

Client → tools/list
Client → tools/call

Registro de herramientas

Las herramientas se registran en McpServerService.cs usando el SDK MCP de .NET. Cada herramienta tiene un nombre, una descripción, un JSON Schema para parámetros y un manejador asíncrono.

Estas son algunas herramientas representativas de las más de 100 disponibles:

Herramienta	Descripción
`Navigate`	Navegar la pestaña activa a una URL
`Click`	Hacer clic en un elemento por selector CSS
`GetElements`	Consultar elementos DOM y extraer atributos
`Screenshot`	Capturar el viewport visible como PNG
`ExecuteScript`	Ejecutar un script `g.*` en el motor de scripting de la aplicación
`StoreGet` / `StorePut`	Leer/escribir almacenamiento del espacio de trabajo
`QueueEnqueue` / `QueueDequeue`	Gestionar colas de trabajo
`SearchQuery`	Búsqueda de texto completo sobre documentos indexados

Por debajo, la mayoría de herramientas delegan en los mismos servicios que impulsan la API de scripting g.*. Navigate llama al mismo BrowserAutomationService.NavigateAsync() que usa g.nav.navigateToUrl(). La capa MCP es un adaptador fino que asigna solicitudes JSON-RPC a llamadas de servicio y formatea los resultados.

Esto significa que scripts y herramientas de IA tienen las mismas capacidades, con una excepción crítica que veremos en la sección de seguridad.

Seguridad en tres capas

Aquí es donde Guida se aparta de la mayoría de servidores MCP. La IA es potente, pero no es de confianza. Toda acción pasa por tres capas de seguridad antes de llegar al navegador.

Capa 1: dominios autorizados

Antes de que la IA pueda navegar a cualquier URL, el dominio debe estar autorizado. Guida soporta tres niveles:

Por sesión - dominios aprobados que caducan al cerrar la aplicación
Por espacio de trabajo - dominios listados en domains.json dentro de la carpeta del espacio de trabajo
Global - dominios permitidos siempre, configurados en ajustes

Si la IA intenta navegar a un dominio que no está autorizado, la llamada a herramienta falla con un mensaje de error claro. La IA ve el rechazo y puede explicar qué ocurrió.

Los comodines funcionan: *.example.com permite todos los subdominios. La restricción de dominios se aplica solo a navegación por scripts; manualmente puede navegar a cualquier sitio.

Capa 2: autorización de herramientas

Incluso en un dominio autorizado, las llamadas a herramientas supervisadas requieren su autorización explícita. Cuando la IA quiere hacer clic en un botón o ejecutar un script, Guida muestra:

El nombre exacto de la herramienta que se llama
Los parámetros exactos: URL, selector, código de script, etc.
Opciones para autorizar una vez, autorizar durante esta sesión o denegar

Es el mismo modelo de permisos que esperaría de una aplicación móvil al pedir acceso a la cámara, salvo que aquí es por acción, no por instalación. Puede confiar en una herramienta durante la sesión si está cansado de aprobar, o revisar cada llamada individualmente.

MCP Approval Center muestra los parámetros reales, no un resumen. Si la IA quiere usar Click con el selector button.delete-account, verá ese selector exacto antes de que se ejecute.

Capa 3: registro de trazabilidad

Cada llamada a herramienta se registra en mcp-audit.db, una base de datos LiteDB separada a la que la IA no puede acceder. El registro de trazabilidad captura:

Nombre de herramienta y parámetros, hasta los primeros 4000 caracteres
Resultado o error, hasta los primeros 2000 caracteres
Duración de ejecución
Marca temporal e ID de sesión

El panel MCP History de la aplicación muestra el registro de trazabilidad en tiempo real. Puede buscar, filtrar por errores y abrir llamadas individuales para ver los parámetros y resultados JSON completos.

La propiedad de seguridad clave es esta: la IA no puede leer ni borrar su propio registro de trazabilidad. No hay herramientas MCP que expongan la base de datos de trazabilidad. Eso significa que incluso una IA afectada por prompt injection no puede cubrir sus huellas.

Aislamiento de credenciales de acceso

Hay otro límite de seguridad que conviene destacar. Guida tiene un panel Secrets donde se guardan claves de API, contraseñas y tokens, cifrados con Windows DPAPI. Los scripts pueden leer credenciales de acceso mediante g.secrets.getSecret(name), pero los scripts originados por MCP no pueden.

Cuando un script se lanza mediante una herramienta MCP, como ExecuteScript, Guida lo etiqueta con origen Mcp. Cualquier llamada a g.secrets.getSecret() desde un script con origen MCP devuelve un error. Esto rompe la cadena de exfiltración:

AI calls ExecuteScript → script calls g.secrets.getSecret("api-key")
                        → BLOCKED (MCP origin detected)

Sin esto, una IA afectada por prompt injection podría ejecutar un script que lea su clave de API, escribirla en g.store y después leer el almacén por MCP. La comprobación de origen impide el primer paso.

Otras operaciones sobre credenciales de acceso, como listar nombres o establecer valores, sí están permitidas; solo se bloquea la lectura de valores descifrados. Esto permite que la IA le ayude a gestionar credenciales sin ver nunca los valores reales.

Herramientas personalizadas

Además de las más de 100 herramientas integradas, puede definir herramientas HTTP personalizadas en el tools.json de un espacio de trabajo:

{
  "tools": [
    {
      "name": "GetWeather",
      "description": "Get current weather for a city",
      "endpoint": "https://api.weather.example/v1/current",
      "method": "GET",
      "parameters": {
        "city": { "type": "string", "description": "City name", "required": true }
      },
      "headers": {
        "Authorization": "Bearer {{secrets.WEATHER_API_KEY}}"
      }
    }
  ]
}

Observe la plantilla {{secrets.WEATHER_API_KEY}}. El valor real de la credencial se inyecta en el momento de la llamada por el servidor; la IA nunca lo ve. Esto permite dar a la IA acceso a API autenticadas sin exponer credenciales.

Las herramientas personalizadas pasan por el mismo flujo de autorización que las integradas. La IA ve el esquema de la herramienta, propone una llamada, y usted autoriza o deniega.

Resumen de arquitectura

Así encajan las piezas:

┌──────────────────────┐
│   AI Client          │  Claude Code, Cursor, etc.
│   (MCP Client)       │
└──────────┬───────────┘
           │ MCP over local HTTP
           │
┌──────────▼───────────┐
│   Guida MCP Server   │  Embedded Kestrel on 127.0.0.1:9315
│                      │
│  ┌─ Domain Filter ─┐ │  Layer 1: authorized-domain check
│  ├─ Approval Center┤ │  Layer 2: User approves/denies
│  ├─ Audit Logger  ─┤ │  Layer 3: Record to mcp-audit.db
│  └─ Tool Handler  ─┘ │  Execute via shared services
│                      │
└──────────┬───────────┘
           │ Service calls
           │
┌──────────▼───────────┐
│   Shared Services    │  BrowserAutomation, Store, Queue,
│                      │  Search, Network, History, etc.
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│   Browser / WebView2 │  Chromium-based browser engine
└──────────────────────┘

El servidor MCP es una capa adaptadora fina. No duplica lógica de negocio: asigna JSON-RPC a los mismos servicios que usan los scripts. Las capas de seguridad, filtro de dominios, autorización y registro de trazabilidad, se insertan como middleware en la canalización MCP.

Conectar un cliente

Para conectar Claude Code u otro cliente MCP a Guida, añada esto a la configuración del cliente MCP:

{
  "mcpServers": {
    "guida": {
      "url": "http://127.0.0.1:9315/"
    }
  }
}

Eso es todo. El cliente descubre las herramientas disponibles mediante el método tools/list y empieza a hacer llamadas. MCP Approval Center de Guida gestiona las solicitudes supervisadas.

Para más detalles sobre las herramientas disponibles y la configuración del espacio de trabajo, consulte la documentación de Integración MCP y la guía de Herramientas personalizadas.