Cómo hacer que Codex CLI lea tus notas y bases de conocimiento de osFoundry por MCP

Al terminar, Codex CLI podrá consultar la Note de especificación, la base de conocimiento de soporte y los Records de bugs de uno de tus proyectos de osFoundry mientras trabaja en tu repositorio. Los lee a través del servidor MCP de osFoundry, te pregunta antes de cualquier cosa que escriba, y cada llamada que hace queda registrada en osFoundry en el Recent activity (actividad reciente) de la conexión. La configuración es una tabla en ~/.codex/config.toml, un inicio de sesión en el navegador y un clic para añadir la conexión a un proyecto.

Quién hace qué

	Lado de Codex	Lado de osFoundry
Inicio de sesión	Tu inicio de sesión habitual de Codex, sin cambios. Codex guarda el token OAuth de osFoundry	Tu cuenta de osFoundry aprueba la conexión una vez, para un workspace
Quién ejecuta el modelo	Codex, en tu máquina, con tu propio plan de Codex	Nadie. En este camino no hay modelo ni clave de proveedor
Dónde se ejecutan las herramientas	Codex envía la llamada a la herramienta por HTTPS	api.osfoundry.io la ejecuta y antes comprueba el acceso
Qué herramientas ve Codex	enabled_tools / disabled_tools en config.toml	La checklist de Tools de la conexión
A qué puede llegar	A lo que devuelva el servidor	Proyectos a los que añadiste la conexión, más los canales a los que la invitaste
Aprobaciones	El aviso propio de Codex, definido por default_tools_approval_mode	Los cambios en GitNest y Room esperan en "Needs your approval" (pendiente de tu aprobación)
Dónde se quedan los datos	Respuestas y diffs se quedan en tu sesión de Codex	Notas, registros y artículos se quedan en osFoundry. Lo que es solo local nunca sale del dispositivo

Configuración

1. Crea la conexión en osFoundry

Haz clic en el icono de la llave en la cabecera de osFoundry y abre la pestaña Connected ("Connected agents", con el nombre del workspace actual debajo). En el formulario bajo "Connect in three steps":

• Assistant: Other MCP client
• Display name: algo que reconozcas, por ejemplo Codex CLI
• Haz clic en Add assistant (añadir asistente)

La conexión aparece como "Setup pending. This assistant cannot read or change anything yet." Copia la Server address:

https://api.osfoundry.io/api/v1/external-mcp

Ejemplo: La pestaña Connected con la conexión Codex CLI seleccionada

2. Añade el servidor a Codex

El comando de una línea de la documentación de MCP de Codex de OpenAI:

codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp

Eso escribe una tabla [mcp_servers.osfoundry]. Abre ~/.codex/config.toml y ajústala. Todas las claves de abajo están en esa documentación:

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write"]
default_tools_approval_mode = "writes"
enabled_tools = [
  "list_granted_resources",
  "list_project_resources",
  "list_note_tabs",
  "read_note_tab",
  "read_sheet_range",
  "search_knowledge_base",
  "read_knowledge_article",
  "list_record_items",
  "read_record_item",
  "edit_record_item",
]

Qué aporta cada línea:

• scopes sustituye lo que ofrece el servidor. Sin ella, Codex toma los scopes del challenge del servidor o de sus protected-resource metadata, y los metadatos de osFoundry enumeran cuatro, incluido osfoundry:run. Un asistente de programación que solo lee y actualiza registros no necesita ejecutar sesiones.
• default_tools_approval_mode = "writes" hace que Codex pida confirmación para cada herramienta que no esté marcada como de solo lectura. osFoundry marca sus herramientas con readOnlyHint, así que las nueve herramientas de lectura se ejecutan sin aviso y edit_record_item pregunta primero.
• enabled_tools mantiene corta la lista de herramientas. El servidor anuncia 59; esta lista tiene diez. Los nombres son los nombres MCP tal cual, sin prefijo. Un nombre mal escrito no da error. Simplemente la herramienta no aparece.

Si el servidor solo debe aplicarse en un repositorio, pon la misma tabla en el .codex/config.toml de ese repositorio. Codex solo lee la configuración de proyecto en los proyectos que hayas marcado como de confianza (trusted).

3. Inicia sesión

codex mcp login osfoundry

El navegador abre https://osfoundry.io/external-assistant-authorize, con el título "Connect an agent". Muestra el Assistant client y "Returns to", que es una dirección local porque Codex recibe el callback en tu máquina. Después:

• Workspace to connect: elige uno. Un segundo workspace necesita su propia conexión.
• Requested capabilities: con los scopes de arriba verás dos líneas, "Read supported resources in projects you add" y "Change supported resources where you have edit access".
• Connection: elige "Use pending: Codex CLI" para que el inicio de sesión se vincule a la conexión del paso 1.
• Marca "I approve connecting this assistant to " y haz clic en Connect.

En una máquina remota por SSH, codex mcp login osfoundry --no-browser imprime la URL en su lugar. La abres en tu portátil y pegas de vuelta en la terminal la URL de redirección completa.

El servidor de osFoundry tiene un endpoint de registro y acepta clientes públicos, así que Codex se registra solo. No tienes que pegar ningún client ID.

4. Añade la conexión a un proyecto

De vuelta en icono de la llave → Connected, la conexión ahora dice "Connected." En Projects, elige el proyecto y haz clic en Add to project (añadir al proyecto). Eso abre las Notes sincronizadas del proyecto, sus bases de conocimiento, canales de Record, Rooms en la nube, repositorios GitNest asignados y su canal de discusión, incluido todo lo que se añada después. Los demás canales de Message necesitan un Invite (invitar) cada uno.

La sección Tools empieza con "All supported tools are on by default." Desmarca lo que esta conexión no deba llamar nunca, aunque alguien edite config.toml más adelante, y haz clic en Save tools (guardar herramientas).

Ejemplo: La checklist de Tools con solo las herramientas de lectura marcadas, y luego Save tools

5. Compruébalo desde Codex

En la TUI de codex, /mcp lista los servidores activos. osfoundry debería estar ahí. Luego pide lo que necesites con palabras normales.

Una ejecución real

Codex no está instalado en la máquina en la que se escribió esto, así que la sesión de abajo es un ejemplo simulado. Los nombres de las herramientas son los que el servidor real devuelve en tools/list. El código fuente de Codex antepone mcp__<server>__ a las herramientas MCP en los nombres que ve el modelo, por eso aparecen así aquí. El prompt, el proyecto y las respuestas son contenido de demostración.

Ejemplo (simulado)

> El test que falla en tests/test_refund.py espera una ventana de 14 días.
  Revisa la especificación de osFoundry y la KB de soporte antes de cambiar nada.

• mcp__osfoundry__list_granted_resources {}
  ← 1 proyecto: "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "note", "search": "reembolso"}
  ← Note "Reglas de reembolso (especificación)"
• mcp__osfoundry__list_note_tabs {"note_id": "…"}
  ← pestañas: Note (texto), Sheet "Casos límite"
• mcp__osfoundry__read_note_tab {"note_id": "…", "tab_id": "…"}
  ← "Los reembolsos se aceptan dentro de los 30 días siguientes a la fecha de la factura…"
• mcp__osfoundry__search_knowledge_base {"knowledge_base_id": "…", "query": "plazo de reembolso"}
  ← artículo "Política de reembolsos", actualizado hace 2 días: 30 días
• edited src/billing/refund.py, tests/test_refund.py
• mcp__osfoundry__edit_record_item {"record_channel_id": "…", "item_id": "…",
      "values": {"status": "Fixed"}, "expected_version": "…", "idempotency_key": "…"}
  [Codex pregunta: ¿permitir esta llamada a la herramienta? → sí]
  ← saved

El que estaba mal era el test, no el código. La Note de especificación y el
artículo de la KB dicen 30 días. Cambié el test y el comentario de la constante,
ejecuté pytest (12 aprobados) y puse el registro "Plazo de reembolso desfasado
16 días" en Fixed.

edit_record_item lleva la versión que devolvió read_record_item o list_record_items, así que un registro que alguien cambió entretanto se rechaza en lugar de sobrescribirse. Un idempotency_key repetido devuelve el primer resultado, así que una llamada reintentada no escribe dos veces. El aviso de aprobación del medio viene de Codex, no de osFoundry, por default_tools_approval_mode = "writes".

Dónde está el límite

Codex lee osFoundry; osFoundry no lee Codex. La conexión permite que Codex llame a herramientas cuando él lo decide. osFoundry registra cada llamada en Recent activity con el nombre de la herramienta, la decisión de acceso y la hora, pero no puede abrir tu sesión de Codex, tu repositorio ni tu terminal. Tu código fuente no va a ninguna parte salvo que Codex lo meta en un argumento de una herramienta, como un comentario en un registro.

Los dos filtros hacen trabajos distintos. enabled_tools en config.toml decide qué se le ofrece al modelo, lo que mantiene el prompt corto y las opciones claras. La checklist de Tools en osFoundry es el interruptor del propietario y sigue vigente diga lo que diga el archivo local. Ninguno de los dos concede acceso a nada. Eso lo hace la pertenencia al proyecto.

El acceso se decide en cada llamada. Cada llamada se comprueba contra el estado de la conexión, su workspace, la pertenencia actual al proyecto, el proyecto en el que está ahora el elemento y tu propio rol en él. Mueve una Note a otro proyecto, quita el proyecto o haz clic en Revoke connection (revocar conexión), y la siguiente llamada de Codex se rechaza aunque su token no haya caducado.

Algunas escrituras son propuestas. El trabajo de GitNest, los change sets, las importaciones de archivos y los pull requests pasan por herramientas propose_… y esperan en la pestaña Connected bajo "Needs your approval", con el destino y los archivos listados, hasta que hagas clic en Approve o Decline. Codex nunca recibe el token de tu proveedor de Git. De todos modos, la configuración de ejemplo de arriba deja fuera esas herramientas, ya que Codex ya tiene tu checkout local.

Los datos solo locales se quedan en local. La respuesta initialize del servidor lo dice: "Local-only data is unavailable to cloud clients." Los Rooms locales, las sesiones de Graph locales y todo lo que no se haya sincronizado no son visibles a través de esta conexión.

Siguiente paso

Apunta Codex a una base de conocimiento que ya uses para responder preguntas y pídele que contraste con ella un docstring o un mensaje de error, por ejemplo: "¿El texto de la KB para este error coincide con lo que imprime el código?". search_knowledge_base devuelve el ID del artículo y cuándo se actualizó por última vez, así que la fuente es fácil de verificar. Cómo las organiza osFoundry está en la página de bases de conocimiento.