Guía de despliegue

ContextForge en un VPS: una pasarela MCP para sus agentes de IA

Desplegar en un VPS Cloud →

ContextForge en un VPS: una pasarela MCP para sus agentes de IA

Cada agente de IA que debe llamar a sus herramientas exige su propia configuración: un servidor MCP por servicio, declarado en cada cliente, con sus credenciales. ContextForge, la pasarela MCP de código abierto de IBM, reúne todo eso tras una sola dirección. Esta guía la instala en un VPS con Docker Compose, la cierra con tokens de API, la publica en HTTPS detrás de nginx, convierte una API REST en herramienta MCP y le conecta un cliente.

7 min de lectura3 pasos
Contenido· Qué hace ContextForge1/12
  1. 01Qué hace ContextForge
  2. 02Lo que aporta la pasarela
  3. 03Conectar cada herramienta o pasar por ContextForge
  4. 04Requisitos previos
  5. 05Instalar ContextForge con Docker Compose
  6. 06No desactive nunca la autenticación
  7. 07Publicar ContextForge en HTTPS con nginx
  8. 08Iniciar sesión y crear un token de API
  9. 09Convertir una API REST en herramienta MCP
  10. 10Agrupar las herramientas y conectar un cliente MCP
  11. 11Respaldar y actualizar
  12. 12Instalación en un clic en ServOrbit

Qué hace ContextForge

ContextForge es una pasarela para el Model Context Protocol (MCP), el protocolo que permite a un agente de IA descubrir y llamar herramientas. Se sitúa entre sus clientes — asistentes de código, frameworks de agentes, automatizaciones — y las herramientas que usan: servidores MCP remotos, API REST o gRPC existentes.

El proyecto lo publica IBM bajo licencia Apache-2.0. Ofrece una API de administración, una consola web, gestión de usuarios y tokens, y servidores virtuales: grupos de herramientas expuestos cada uno en su propia dirección MCP. En un VPS, es el punto de entrada único de sus agentes.

Lo que aporta la pasarela

  • Una sola dirección — sus clientes se conectan a la pasarela, no a cada herramienta.
  • API REST convertidas en herramientas — una URL, un método y un esquema de entrada, sin escribir un servidor MCP.
  • Servidores virtuales — un conjunto de herramientas por agente, proyecto o cliente.
  • La federación — servidores MCP remotos registrados y expuestos en el mismo lugar.
  • Tokens de API — uno por cliente, con fecha de caducidad, revocables uno a uno.
  • Una consola web — herramientas, servidores, tokens y usuarios gestionados desde /admin.

Conectar cada herramienta o pasar por ContextForge

Desplace la tabla

Un servidor MCP por herramientaContextForge
Configuración de los clientesUna herramienta que declarar en cada clienteUna dirección y un token
Credenciales de los serviciosCopiadas en cada clienteGuardadas por la pasarela
API REST existenteUn servidor MCP que escribirDeclarada como herramienta
Retirar un accesoCliente por clienteRevocar un token
Herramientas que ve un agenteTodas las que tiene configuradasLas de su servidor virtual

Requisitos previos

Un VPS Ubuntu 24.04 con 2 GB de RAM y 2 vCPU es suficiente: con dos procesos de trabajo, la pasarela ocupa unos 800 MB de memoria. Los datos caben en una base SQLite de pocos megabytes.

Necesita Docker con el plugin Compose, nginx y certbot en el host, jq para leer las respuestas de la API y un nombre (mcp.example.com en esta guía) que apunte a la IP del VPS.

Instalar ContextForge con Docker Compose

  1. Generar los secretos

    En una carpeta dedicada, escriba un archivo .env con el nombre de dominio, la contraseña de administrador y dos secretos distintos: SECRET_KEY firma los tokens y ENCRYPTION_KEY_HEX64 cifra las credenciales de los servidores que registre. ContextForge se niega a arrancar con secretos demasiado cortos o con su valor de ejemplo.

    mkdir -p /opt/contextforge && cd /opt/contextforge
    cat > .env <<EOF
    DOMAIN=mcp.example.com
    ADMIN_PASSWORD=$(openssl rand -base64 18)
    SECRET_KEY=$(openssl rand -hex 32)
    ENCRYPTION_KEY_HEX64=$(openssl rand -hex 32)
    EOF
    chmod 600 .env
  2. Escribir el archivo docker-compose.yml

    La imagen se ejecuta con un usuario sin privilegios (uid 10001): el servicio contextforge-init hace escribible el volumen antes del arranque. AUTH_REQUIRED y MCP_REQUIRE_AUTH cierran la API y el punto MCP, y el puerto solo se publica en la interfaz local. DEFAULT_USER_PASSWORD, la contraseña provisional de las cuentas creadas sin contraseña, se genera al azar en cada arranque.

    services:
      contextforge-init:
        image: ghcr.io/ibm/mcp-context-forge:v1.1.1
        user: "0:0"
        entrypoint: ["chown", "-R", "10001:10001", "/app/data"]
        restart: "no"
        volumes:
          - contextforge-data:/app/data
    
      contextforge:
        image: ghcr.io/ibm/mcp-context-forge:v1.1.1
        restart: unless-stopped
        depends_on:
          contextforge-init:
            condition: service_completed_successfully
        environment:
          HOST: "0.0.0.0"
          PORT: "4444"
          ENVIRONMENT: "production"
          APP_DOMAIN: "https://${DOMAIN}"
          ALLOWED_ORIGINS: "https://${DOMAIN}"
          DATABASE_URL: "sqlite:////app/data/mcp.db"
          CACHE_TYPE: "database"
          GUNICORN_WORKERS: "2"
          MCPGATEWAY_UI_ENABLED: "true"
          MCPGATEWAY_ADMIN_API_ENABLED: "true"
          AUTH_REQUIRED: "true"
          MCP_CLIENT_AUTH_ENABLED: "true"
          MCP_REQUIRE_AUTH: "true"
          EMAIL_AUTH_ENABLED: "true"
          PLATFORM_ADMIN_EMAIL: "[email protected]"
          PLATFORM_ADMIN_PASSWORD: "${ADMIN_PASSWORD}"
          JWT_SECRET_KEY: "${SECRET_KEY}"
          AUTH_ENCRYPTION_SECRET: "${ENCRYPTION_KEY_HEX64}"
        entrypoint: ["/bin/bash", "-c"]
        command:
          - |
            export DEFAULT_USER_PASSWORD="$$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')"
            exec ./docker-entrypoint.sh
        ports:
          - "127.0.0.1:4444:4444"
        volumes:
          - contextforge-data:/app/data
    
    volumes:
      contextforge-data: {}
  3. Arrancar y comprobar

    Inicie la pila y consulte el punto de salud. La primera vez, ContextForge crea su base y la cuenta de administrador; el contenedor pasa a healthy en menos de un minuto.

    docker compose up -d
    docker compose ps
    curl -s http://127.0.0.1:4444/health

    La respuesta esperada es {"status":"healthy"}. Cualquier otra ruta, /tools o /version por ejemplo, responde 401 sin token.

No desactive nunca la autenticación

Una pasarela MCP abierta entrega a cualquiera las herramientas que conectó — y las credenciales que las acompañan. Mantenga AUTH_REQUIRED y MCP_REQUIRE_AUTH en true, el puerto en 127.0.0.1, y deje a nginx solo frente a Internet.

Publicar ContextForge en HTTPS con nginx

Cree un server block en /etc/nginx/sites-available/ y actívelo. X-Forwarded-Proto importa: la consola compara el origen del formulario de inicio de sesión con la dirección de la solicitud, y rechaza el acceso si no coinciden. proxy_buffering off deja pasar las respuestas en flujo del protocolo MCP.

server {
    server_name mcp.example.com;

    location / {
        proxy_pass http://127.0.0.1:4444;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 300s;
    }
}

Compruebe la configuración y solicite el certificado:

sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d mcp.example.com

Iniciar sesión y crear un token de API

Abra https://mcp.example.com/admin e inicie sesión con [email protected] y la contraseña del archivo .env. La consola permite crear tokens, y la API también. El inicio de sesión devuelve un token de sesión de corta duración, que sirve para crear un token de API con nombre, válido 30 días aquí:

SESSION=$(curl -s https://mcp.example.com/auth/email/login -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"SU_CONTRASENA"}' | jq -r .access_token)
TOKEN=$(curl -s https://mcp.example.com/tokens -H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" \
  -d '{"name":"agent-1","expires_in_days":30}' | jq -r .access_token)

Cree un token por cliente o por agente: podrá revocar uno sin tocar los demás.

Convertir una API REST en herramienta MCP

Una herramienta REST se declara con su URL, su método y el esquema de sus parámetros. El ejemplo siguiente expone la API pública zen de GitHub, que devuelve una frase y no espera ningún parámetro:

curl -s https://mcp.example.com/tools -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"tool":{"name":"github_zen","url":"https://api.github.com/zen","integration_type":"REST","request_type":"GET","input_schema":{"type":"object","properties":{}}}}' \
  | jq -r .id

El comando muestra el identificador de la herramienta. En MCP, su nombre pasa a ser github-zen. Para una API interna, cambie la URL y describa sus parámetros en input_schema: es el esquema que lee el agente para saber cómo llamarla.

Agrupar las herramientas y conectar un cliente MCP

Un servidor virtual agrupa herramientas bajo una dirección MCP. Créelo con el identificador de la herramienta:

curl -s https://mcp.example.com/servers -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"server":{"name":"demo","associated_tools":["ID_HERRAMIENTA"]}}' | jq -r .id

Luego compruebe, como lo haría un cliente, que la herramienta aparece en la lista:

curl -s https://mcp.example.com/servers/ID_SERVIDOR/mcp -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

En su cliente MCP, declare la dirección del servidor virtual y el token. La forma exacta depende del cliente; muchos aceptan una entrada como esta:

{
  "mcpServers": {
    "contextforge": {
      "type": "http",
      "url": "https://mcp.example.com/servers/ID_SERVIDOR/mcp",
      "headers": { "Authorization": "Bearer SU_TOKEN" }
    }
  }
}

Respaldar y actualizar

Qué respaldar: el volumen contextforge-data, que contiene la base SQLite — herramientas, servidores, usuarios y tokens — y el archivo .env. Sin ENCRYPTION_KEY_HEX64, las credenciales cifradas de la base ya no se pueden leer. Detenga el servicio durante la copia:

cd /opt/contextforge
docker compose stop contextforge
docker compose cp contextforge:/app/data ./respaldo-$(date +%F)
docker compose start contextforge

Para actualizar, cambie la etiqueta de la imagen en los dos servicios tras leer las notas de la versión y luego:

docker compose pull
docker compose up -d

ContextForge aplica sus migraciones de base de datos al arrancar: haga el respaldo antes.

Instalación en un clic en ServOrbit

En un VPS de ServOrbit, ContextForge se instala desde el Marketplace: el script despliega la imagen oficial, genera la contraseña de administrador y los secretos, cierra la instancia a cualquier solicitud sin token y configura nginx en HTTPS. La dirección es un subdominio de uno de sus dominios o el subdominio gratuito del VPS, certificado incluido, y la contraseña aparece en su área de cliente.

Compartir este artículoservorbit.com/ma-es/blog/autoalojar-contextforge-vps-pasarela-mcp