Secure Local Workspace MCP (MCP de espacio de trabajo local seguro)

English | 中文（默认）

Permite que la versión web de ChatGPT se conecte de forma segura a proyectos locales: tanto si usas Git como si no, puedes ver, buscar y modificar archivos, y ejecutar tareas de la lista blanca; en proyectos Git también puedes revisar diferencias, crear commits locales y, tras la autorización explícita del usuario, hacer push a un remoto y rama especificados.

No necesitas instalar Codex. ChatGPT invoca el servicio MCP que sigue ejecutándose en tu ordenador a través de OpenAI Secure MCP Tunnel; el directorio del proyecto y el puerto MCP no necesitan exponerse a Internet.

Elige primero tu escenario de uso

Related MCP server: Kastor

Qué obtendrás

El proyecto no ofrece shell arbitrario, git add ., push forzado, reescritura de historial, despliegue en producción ni acceso arbitrario al disco.

Primera instalación: conectar ChatGPT desde cero

El siguiente flujo usa Windows PowerShell como ejemplo. Normalmente solo hay que hacerlo una vez.

Paso 1: Comprobar los requisitos previos

Necesitas:

• Windows PowerShell;

• Git;

• Node.js 20 o superior;

• Poder usar el modo desarrollador de ChatGPT;

• Permisos de Tunnel en OpenAI Platform.

Comprueba los comandos de tu máquina:

git --version
node --version
npm --version

Si piensas permitir que ChatGPT cree commits de Git, también debes configurar primero la identidad de Git. Si ya la tienes configurada, puedes omitirlo:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Paso 2: Descargar el proyecto

git clone https://github.com/dxawdc/secure-local-workspace-mcp.git
Set-Location .\secure-local-workspace-mcp

Paso 3: Preparar el Tunnel en la página de OpenAI

Sigue la documentación oficial de OpenAI Secure MCP Tunnel para completar lo siguiente:

1. Crea un Tunnel en OpenAI Platform;

2. Asocia el Tunnel al workspace de ChatGPT que vaya a usarlo;

3. Crea una Runtime API Key para que la use tunnel-client;

4. Descarga la última versión oficial de tunnel-client;

5. Anota el tunnel_id y la ruta local de tunnel-client.exe.

Estos pasos implican permisos de cuenta y claves, y deben ser confirmados por el usuario en la página de OpenAI; el proyecto no crea ni lee credenciales de cuenta en lugar del usuario.

Paso 4: Guardar la Runtime Key fuera del repositorio

No escribas la Key en el README, en la configuración del proyecto, en Git ni en el historial de comandos de PowerShell. Puedes crear primero un archivo fuera del repositorio:

New-Item -ItemType Directory -Path "C:\Secrets" -Force
notepad "C:\Secrets\openai-tunnel-runtime-key.txt"

Pega la Runtime Key en el Bloc de notas, deja solo una línea, guarda y cierra. En entornos de producción o de equipo, usa un esquema de gestión de claves aprobado por la organización y restringe los permisos de acceso a ese archivo.

Paso 5: Ejecutar la configuración con un clic

Sustituye las tres rutas del ejemplo y el Tunnel ID por tus propios valores:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -DiscoveryRoot "D:\Projects" `
  -TunnelId "tunnel_REPLACEME" `
  -TunnelClient "C:\Tools\tunnel-client\tunnel-client.exe" `
  -ControlPlaneApiKeyRef "file:C:\Secrets\openai-tunnel-runtime-key.txt" `
  -RegisterStartup `
  -StartTunnel

Cómo rellenar los parámetros:

• ProjectRoot: el directorio del proyecto que vas a entregar a ChatGPT para que opere; no tiene que ser un repositorio Git;

• DiscoveryRoot: el directorio padre que permite a ChatGPT descubrir proyectos; normalmente el nivel superior de ProjectRoot;

• TunnelId: el tunnel_id real que muestra OpenAI Platform;

• TunnelClient: el tunnel-client.exe descargado y descomprimido;

• ControlPlaneApiKeyRef: la ruta del archivo de la Runtime Key, debe llevar el prefijo file:.

El script completará automáticamente:

1. Instalar las dependencias de Node.js usando el archivo de bloqueo;

2. Ejecutar pruebas unitarias y pruebas de humo de MCP;

3. Configurar el proyecto como de lectura/escritura y permitir commits locales;

4. Aprobar el directorio de descubrimiento de proyectos;

5. Detectar automáticamente test, lint, build, typecheck en package.json;

6. Crear y comprobar el perfil de Tunnel;

7. Registrar una tarea de inicio de sesión del usuario actual y arrancar el Tunnel inmediatamente.

Por defecto no se permite push. Los proyectos no Git conservan automáticamente la capacidad de lectura/escritura de archivos, mientras que commit y push quedan forzados a desactivado, sin necesidad de añadir -DisableCommit manualmente.

Si tu máquina necesita un proxy para acceder a OpenAI, añade al final del comando:

-HttpProxy "http://127.0.0.1:7890"

Paso 6: Crear una aplicación privada en ChatGPT

1. Habilita el modo desarrollador en la configuración de ChatGPT. Los usuarios de Enterprise/Edu pueden necesitar autorización del administrador;

2. Abre ChatGPT Plugins;

3. Haz clic en el signo más para crear una aplicación de modo desarrollador;

4. En Connection, selecciona Tunnel;

5. Selecciona el Tunnel que acabas de crear o pega el tunnel_id real;

6. Crea la aplicación y espera a que ChatGPT descubra las herramientas.

Las instrucciones oficiales requieren que tunnel-client siga ejecutándose; de lo contrario, ChatGPT no podrá descubrir ni invocar las herramientas.

Paso 7: Verificar la conexión

En una conversación nueva de ChatGPT, selecciona o menciona con @ esta aplicación y envía:

调用 diagnostics 和 list_projects。
告诉我 Tunnel 后面的本地 MCP 是否正常，并列出已授权项目、读写权限、commit 权限和 push 权限。
不要修改任何文件。

En condiciones normales deberías ver la lista de proyectos y el allowPush por defecto en false. La nueva versión ofrece 17 herramientas en total; si siguen apareciendo las herramientas antiguas, reinicia el Tunnel y actualiza la aplicación en ChatGPT o abre una conversación nueva.

Con Tunnel existente: incorporar un nuevo proyecto

Si el Tunnel y la tarea de inicio de sesión se configuraron a través de este proyecto, ejecuta en el directorio del repositorio:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\another-app" `
  -DiscoveryRoot "D:\Projects" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Esto añade o actualiza la configuración del proyecto sin sobrescribir otros proyectos ya autorizados.

Si no has registrado la tarea de inicio de sesión con este proyecto, quita -RestartTunnel y, tras completar la configuración, reinicia tunnel-client con tu método habitual. Después de reiniciar, actualiza las herramientas en la configuración de la aplicación de ChatGPT.

Deja que ChatGPT conecte automáticamente proyectos no Git

Los directorios de proyectos comunes de Node.js, Python, Java, Go, Rust, .NET, PHP, Ruby, Elixir, Swift, CMake, etc., se detectan automáticamente con discover_projects. Incluso si el directorio no tiene marcadores de proyecto comunes, se puede conectar dentro de un DiscoveryRoot aprobado usando una ruta absoluta explícita:

调用 discover_projects，列出已批准目录中的 Git 和非 Git 项目。
把 D:\Projects\notes-app 接入为可读写项目。
如果它不是 Git 仓库，必须自动关闭 commit 和 push。
接入后调用 list_projects，确认 projectType 和最终权限。

Tras la llamada de ChatGPT a connect_project, la configuración se persiste inmediatamente y surte efecto en el proceso MCP actual; no es necesario reiniciar el Tunnel para un proyecto individual.

Solo permitir ver, no modificar

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\reference-project" `
  -DiscoveryRoot "D:\Projects" `
  -ReadOnly `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Permitir modificar, pero no hacer commit

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -DiscoveryRoot "D:\Projects" `
  -DisableCommit `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Añadir solo un directorio padre de proyectos descubribles

.\scripts\quick-setup.ps1 `
  -DiscoveryRoot "E:\OtherProjects" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

No establezcas DiscoveryRoot como la raíz del disco, todo el directorio de usuario o un directorio con muchos archivos personales. Debe ser un directorio padre dedicado a alojar repositorios de código.

Indicaciones de uso diario

El nombre del proyecto se rige por el ID que devuelve list_projects. Las siguientes indicaciones se pueden copiar directamente a ChatGPT y luego sustituir el nombre del proyecto y los requisitos.

1. Solo ver y analizar

使用 Secure Local Workspace MCP 检查项目 my-app。
先调用 list_projects 确认项目，再查看与登录流程有关的代码。
解释实现和可能的问题，不要修改文件，不要提交。

2. Modificar y probar, pero sin commit

检查项目 my-app 的重复提交问题并完成修复。
修改前重新读取目标文件并使用最新 SHA-256，只改与本次问题有关的文件。
运行项目允许的 test 或 lint 任务，最后展示 git_status 和 git_diff。
不要 commit，不要 push。

3. Modificar, probar y crear un commit local

修复项目 my-app 的重复提交问题。
运行相关测试，然后展示完整 git_diff 和 git_status。
确认差异只包含本次修改后，使用最新 statusSha256，
只提交本次涉及的明确文件，提交信息为：fix: prevent duplicate submissions。
提交后报告本地 commit SHA。不要 push。

4. Solo hacer commit de los cambios ya completados

检查项目 my-app 当前 git_status 和 git_diff，不要继续改代码。
如果存在与本任务无关或已经预暂存的文件，停止并告诉我。
否则使用最新 statusSha256，只提交这些明确文件：src/example.js、test/example.test.js。
提交信息为：fix: handle duplicate submissions。不要 push。

git_commit rechazará:

• ., directorios o rutas fuera del proyecto;

• estados de Git que hayan cambiado tras la revisión;

• cambios ya preparados (staged) preexistentes;

• rutas sensibles como .env, claves privadas, certificados, almacenes de contraseñas, etc.;

• API Keys, Tokens, claves privadas de alta confianza o identificadores reales de Tunnel/organización;

• fallos de git diff --cached --check;

• commit no habilitado en la configuración local.

Que el commit tenga éxito solo significa que se ha hecho commit localmente, no que se haya hecho push.

Habilitar push controlado por separado

El push es una operación de escritura externa, por lo que debe activarse explícitamente en la máquina local para cada proyecto. Se recomienda limitar también la rama de destino:

.\scripts\quick-setup.ps1 `
  -ProjectRoot "D:\Projects\my-app" `
  -AllowPush `
  -AllowedRemote "origin" `
  -AllowedBranch "main" `
  -SkipInstall `
  -SkipTests `
  -RestartTunnel

Luego pide explícitamente en ChatGPT:

检查项目 my-app 当前分支、HEAD、git_status 和待推送 commit。
只有在工作区状态和 commit 都符合预期时，才把当前 HEAD 推送到允许的 origin/main。
禁止 force push。分别报告本地 commit SHA、远端分支和推送结果。

git_push no crea commits automáticamente ni hace push a remotes o ramas no configurados.

Límites entre automatización y operaciones manuales

Para una configuración por lotes más detallada, proxy, inicio automático, reversión y operación desatendida, consulta: Flujo de configuración automatizada de Windows.

Gestión de configuración

El archivo de configuración por defecto se encuentra fuera del repositorio:

%USERPROFILE%\.secure-local-workspace-mcp\config.json

Si la configuración de la nueva versión no existe, el servicio lee de forma compatible la ruta antigua:

%USERPROFILE%\.local-project-workspace\config.json

Ver la configuración actual:

npm run config -- list

Si no usas la automatización de PowerShell, también puedes invocar la CLI de configuración multiplataforma:

npm run config -- add-discovery-root --root "D:\Projects"

npm run config -- add-project `
  --root "D:\Projects\my-app" `
  --writable `
  --allow-commit `
  --no-push

El script compatible bootstrap-config.ps1 también añade o actualiza un único proyecto de forma idempotente, sin reemplazar toda la configuración.

Actualizar el proyecto

Set-Location .\secure-local-workspace-mcp
git pull --ff-only
npm ci
npm test
npm run smoke:mcp

Tras actualizar el código o las definiciones de herramientas, debes reiniciar tunnel-client y actualizar la aplicación en ChatGPT o abrir una conversación nueva.

Revocar el acceso a un proyecto

Envía en ChatGPT:

调用 disconnect_project 撤销项目 my-app 的 MCP 访问权限，然后重新列出项目。

Esto solo elimina la configuración de autorización local; no elimina el directorio del proyecto, los archivos ni el historial de Git.

Si necesitas eliminar la tarea de inicio de sesión:

Stop-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel"
Unregister-ScheduledTask -TaskName "Secure Local Workspace MCP Tunnel" -Confirm:$false

Esto no elimina el Tunnel, la Runtime Key, el perfil ni los archivos del proyecto.

Preguntas frecuentes

Git commit identity is missing

Configura primero el nombre de usuario y el correo de Git y vuelve a ejecutar la configuración:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Scheduled task not found

Has usado -RestartTunnel, pero el Tunnel no se registró a través de este proyecto. Quita ese parámetro para completar la configuración del proyecto y reinicia tunnel-client con tu método habitual.

No veo el Tunnel en ChatGPT

Comprueba en orden:

1. Si el Tunnel está asociado al workspace actual de ChatGPT y no solo a la organización de Platform;

2. Si la cuenta actual tiene Tunnels Read + Use;

3. Si el modo desarrollador de ChatGPT está habilitado;

4. Si tunnel-client sigue ejecutándose y en estado healthy/ready.

ChatGPT no descubre las 17 herramientas

• Reinicia el runtime del Tunnel;

• Ejecuta tunnel-client doctor --profile <profile> --explain;

• Actualiza en la configuración de la aplicación de ChatGPT;

• Abre una conversación nueva de ChatGPT para evitar que la conversación anterior siga usando definiciones de herramientas en caché.

El proyecto no se puede descubrir ni conectar

• El proyecto debe estar dentro de un DiscoveryRoot aprobado;

• Los repositorios Git y los directorios no Git con marcadores de proyecto comunes aparecen automáticamente en los resultados de descubrimiento;

• Los directorios normales sin marcadores de proyecto no se listan automáticamente, pero puedes hacer que ChatGPT llame a connect_project con su ruta absoluta explícita;

• Los proyectos no Git muestran projectType: non-git y tienen commit y push forzados a desactivado;

• Ejecuta npm run config -- list para comprobar la configuración real;

• Si es necesario, vuelve a añadir el directorio padre y reinicia el Tunnel.

Escritura rechazada o aviso de SHA caducado

• El proyecto debe permitir escritura;

• Antes de modificar o eliminar un archivo existente, ChatGPT debe volver a llamar a read_file;

• Si otro programa modifica el archivo, el SHA antiguo deja de ser válido; es una protección normal contra concurrencia.

Commit rechazado por cambios ya preparados (staged)

Haz que ChatGPT llame primero a git_status para comprobarlo. Si confirmas que se puede cancelar la preparación, llama a git_unstage para procesar los archivos explícitos; esta operación no descarta el contenido del área de trabajo.

El Tunnel funciona localmente, pero ChatGPT agota el tiempo de espera

• Comprueba la conexión saliente a api.openai.com:443;

• Que el navegador use un proxy no significa que tunnel-client use automáticamente el mismo proxy;

• En la primera configuración, escribe el proxy con -HttpProxy;

• Comprueba el firewall local, los certificados del proxy y las políticas de red de la organización.

Verificación local

npm ci
npm test
npm run smoke:mcp
npm audit --omit=dev

Arranque local de MCP en primer plano:

.\scripts\start-local.ps1

El estado del Tunnel debe cumplir al menos:

process_running = true
healthy = true
ready = true

Recomendaciones de seguridad

• Discovery Root debe ser un directorio padre dedicado a proyectos; no uses la raíz del disco ni todo el directorio de usuario;

• Prioriza habilitar solo commit; habilita push solo cuando sea realmente necesario, por proyecto, remote y branch;

• La Runtime Key, el perfil de Tunnel, la configuración real y los registros deben guardarse fuera del repositorio;

• El commit de MCP desactiva temporalmente los Git hooks del proyecto; las pruebas y el formateo deben ejecutarse mediante la lista blanca de tareas explícitas;

• Antes del push, sigue verificando el SHA de commit, el remote y la branch explícitos;

• Si una clave se confirma por error, revócala de inmediato y limpia todo el historial de Git.

Para el diseño de seguridad y la notificación de vulnerabilidades, consulta SECURITY.md.

Referencias oficiales

• OpenAI Secure MCP Tunnel

• OpenAI MCP and Connectors

Licencia

MIT