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 herramienta | ContextForge | |
|---|---|---|
| Configuración de los clientes | Una herramienta que declarar en cada cliente | Una dirección y un token |
| Credenciales de los servicios | Copiadas en cada cliente | Guardadas por la pasarela |
| API REST existente | Un servidor MCP que escribir | Declarada como herramienta |
| Retirar un acceso | Cliente por cliente | Revocar un token |
| Herramientas que ve un agente | Todas las que tiene configuradas | Las 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
Generar los secretos
En una carpeta dedicada, escriba un archivo
.envcon el nombre de dominio, la contraseña de administrador y dos secretos distintos:SECRET_KEYfirma los tokens yENCRYPTION_KEY_HEX64cifra 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 .envEscribir el archivo docker-compose.yml
La imagen se ejecuta con un usuario sin privilegios (uid 10001): el servicio
contextforge-inithace escribible el volumen antes del arranque.AUTH_REQUIREDyMCP_REQUIRE_AUTHcierran 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: {}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
healthyen menos de un minuto.docker compose up -d docker compose ps curl -s http://127.0.0.1:4444/healthLa respuesta esperada es
{"status":"healthy"}. Cualquier otra ruta,/toolso/versionpor 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.comIniciar 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 .idEl 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 .idLuego 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 contextforgePara 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 -dContextForge 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.
servorbit.com/ma-es/blog/autoalojar-contextforge-vps-pasarela-mcp