DEV Community: BBT Español

Cómo usar Claude Code como worker de osFoundry con tu propia suscripción de Claude

BBT — Sat, 07 Nov 2026 16:50:52 +0000

Al terminar esta configuración, el rol Worker de osFoundry lo ocupa Claude Code. Cuando un paso del plan le llega, la app de escritorio arranca claude en la carpeta de tu proyecto, con la sesión iniciada en tu propia suscripción de Claude. Claude Code edita archivos con sus propias herramientas y accede a las herramientas de osFoundry, como la búsqueda en tus notas, con el nombre mcp__osfoundry__memory_search. Cada una de esas llamadas aparece en el chat de osFoundry como una línea "Using …".

Quién hace qué

	Claude Code	App de escritorio de osFoundry
Inicio de sesión	Tu suscripción de Claude, que la CLI guarda después de `/login`	Nunca la ve. Quita `ANTHROPIC_API_KEY` y variables similares del entorno del proceso hijo para que la ejecución no pueda pasar a facturación por API
Coste	Sale de tu suscripción	Registra la ejecución con coste 0
Archivos	Sus propios Read, Edit y Bash, dentro de una sola carpeta (`--add-dir`)	Elige esa carpeta: la más reciente en Local Folders
Herramientas de osFoundry	Las llama como `mcp__osfoundry__<tool>`	Las sirve en un puerto loopback solo durante esta ejecución y comprueba cada llamada contra una allowlist
Aprobación	Se ejecuta con `--permission-mode bypassPermissions` en su carpeta	Cada llamada que pasa por el bridge atraviesa la misma puerta de aprobación y políticas que la llamada a herramienta de cualquier otro modelo
Salida	Texto final	Se convierte en la salida del rol. La actividad de las herramientas se muestra como líneas de progreso

Configuración

1. Instala Claude Code e inicia sesión una vez

Instala la CLI tal como lo documenta Anthropic. Después inicia sesión desde una terminal:

$ claude
> /login

osFoundry busca el binario en PATH, en ~/.claude/local y dentro del paquete de la extensión de VS Code (~/.vscode/extensions/anthropic.claude-code-*/resources/native-binary/claude). Así que también encuentra un Claude Code que solo vino con la extensión de VS Code.

2. Actívalo en External AI

En la app de escritorio, haz clic en el icono de la llave de la cabecera (API Keys (BYOK)) y abre la pestaña External AI (IA externa). La fila de Claude Code debería verse así:

Claude Code   Installed                                  [Enabled]
/Users/you/.claude/local/claude
Model id: cli:claude (chat) · cli:claude:agent (autonomous)
[Verify sign-in]  [Sign in]

Ejemplo: Claude Code y Codex en la pestaña External AI

Haz clic en Verify sign-in (verificar inicio de sesión). La app ejecuta una completion mínima a través de la CLI y muestra ✓ Signed in o Needs sign-in. Sign in abre Claude Code en una ventana de terminal con la indicación "Type /login to sign in, then close this window."

Puede que veas una insignia API key in env. Significa que hay una variable como ANTHROPIC_API_KEY definida en el entorno desde el que se lanzó osFoundry. La app la elimina antes de arrancar claude, así que la ejecución sigue usando tu suscripción. La insignia es solo un aviso.

3. Dale una carpeta

El modo agente trabaja en un directorio real. Añade tu proyecto en Settings → Local Folders. Si tienes varios, se usa el último que añadiste. Las ejecuciones iniciadas desde la superficie Code usan en su lugar el repositorio registrado para esa ejecución.

4. Asigna el rol

Abre la pestaña Pipeline → Pipeline Roles. En Agents, elige Worker y selecciona cli:claude:agent en el grupo External AI (subscription).

Los dos ids corresponden a dos modos distintos:

cli:claude:agent es autónomo. Claude Code tiene sus propias herramientas en tu carpeta, más las herramientas de osFoundry a través del bridge. Úsalo para Worker, Researcher, Document Agent y roles parecidos.
cli:claude es el modo chat. La CLI se ejecuta con --disallowedTools '*' y no puede llamar a nada. Sirve para roles solo de texto como Titling o Compaction. Si se asigna a un rol que necesita herramientas, la ejecución falla con un mensaje que te indica usar cli:claude:agent.

Los agentes que defines en la pantalla Agents también pueden usarlo. Su selector de modelo lo muestra bajo CLI agents, con la etiqueta "autonomous — runs in your local folder".

5. Lo que la app arranca realmente

En cada ejecución, osFoundry levanta un bridge MCP nuevo y luego lanza la CLI más o menos así. Los flags salen de build_claude_command en src-tauri/src/providers/agent_cli.rs:

claude -p "<conversation>" \
  --output-format stream-json --verbose --include-partial-messages \
  --permission-mode bypassPermissions \
  --add-dir /Users/you/work/site \
  --mcp-config '{"mcpServers":{"osfoundry":{"type":"http",
      "url":"http://127.0.0.1:<port>/mcp",
      "headers":{"Authorization":"Bearer <per-run token>"},
      "timeout":120000}}}' \
  --strict-mcp-config \
  --append-system-prompt "<role prompt>"

--strict-mcp-config deja fuera de esta ejecución tus propios servidores MCP globales o de proyecto. Solo se conecta el servidor osfoundry. El puerto y el token son nuevos en cada ejecución, y el listener se cierra cuando el proceso termina.

Una ejecución real

Ejemplo. La nota y el repositorio son contenido de demostración.

Tú (chat de Maestro, Worker = cli:claude:agent)
  Busca en mis notas cuándo es la revisión del presupuesto del Q4 y añádelo a TODO.md.

Llamadas a herramientas de Claude Code
  mcp__osfoundry__memory_search  {"query": "revisión del presupuesto del Q4"}
    → "Revisión del presupuesto del Q4: jue 14:00."
  Read   TODO.md
  Edit   TODO.md   (+ "- [ ] Preparar las cifras para la revisión del presupuesto del Q4 (jue 14:00)")

Líneas de progreso de osFoundry
  Using memory_search — {"query":"revisión del presupuesto del Q4"}
  Using Read — {"file_path":"TODO.md"}
  Using Edit — {"file_path":"TODO.md", …}

Respuesta
  Añadido "Preparar las cifras para la revisión del presupuesto del Q4 (jue 14:00)" a TODO.md.
  La hora viene de tu nota "Revisión del presupuesto del Q4: jue 14:00."

El prefijo mcp__osfoundry__ es la forma en que Claude Code nombra las herramientas de un servidor llamado osfoundry. osFoundry lo quita en la línea de progreso, así que memory_search se lee igual que con un modelo por API.

Dónde está el límite

El bridge ofrece una lista corta y fija. Incluye herramientas de solo lectura como memory_search, web_search, extract_content, code_search, todo_list, transcribe y las herramientas de lectura cloud_*, además de la orquestación (spawn_fleet, graph_run, loop_run), la pantalla en vivo y las herramientas de Canvas. Deja fuera a propósito read_file, write_file y execute_command. Claude Code ya tiene versiones de esas limitadas a su carpeta, y un segundo ejecutor sin ese límite por MCP llegaría más allá de --add-dir.

La allowlist la aplica el bridge, no un flag de la CLI. Una ejecución en modo bypassPermissions no respeta --allowedTools, así que osFoundry no lo pasa. Una llamada a cualquier herramienta fuera de la lista de la ejecución recibe un error JSON-RPC: "tool '…' is not available to this agent".

El workspace y el canal quedan fijados cuando arranca el bridge. Una llamada a herramienta no puede redirigirse a otro workspace mediante sus argumentos.

Las escrituras en la pantalla o en un editor de Canvas (ui_agent_act, las herramientas de escritura de Canvas) siempre te preguntan antes, igual que con un modelo por API. Las ejecuciones que nadie está mirando, como un agente que responde a una mención en un canal, rechazan una herramienta que necesita aprobación en lugar de esperar un clic que no va a llegar.

Tus archivos nunca pasan por osFoundry. Claude Code los lee y edita directamente, y su tráfico va a Anthropic con tu propio inicio de sesión, como iría desde una terminal.

El siguiente paso es asignar cli:claude:agent también al rol Researcher, junto a Worker, y lanzar una tarea orquestada. La página de roles del Pipeline enumera todos los roles que puedes darle, y Local Folders explica cómo se elige la carpeta de trabajo.

¿Cómo evita osFoundry que una edición de Claude sobrescriba la de una persona en la misma Note?

BBT — Sat, 07 Nov 2026 16:38:15 +0000

Esta es la herramienta de escritura que recibe un chat de Claude para las Notes de osFoundry, tal como la lista el endpoint MCP público. Se obtuvo con un tools/list sin autenticar el 2026-11-06 y se recortó a los campos que importan aquí:

{"name": "edit_note_tab",
 "description": "Use an exact tab ID and version from read_note_tab. Use replace_text for Note/Markdown, slide_add or slides_add_outline for Slides, sheet_set_range for Sheet, or replace_tab_data for supported content tabs. File and Source attachments cannot be edited through this tool. A repeated idempotency key returns the first result.",
 "inputSchema": {
   "required": ["note_id", "tab_id", "expected_version", "idempotency_key", "operation"],
   "properties": {
     "operation": {"enum": ["replace_text", "replace_tab_data", "slide_add",
                            "slides_add_outline", "sheet_set_range"]},
     "sheet_id": {"type": "string"}, "start_row": {"type": "integer"},
     "start_col": {"type": "integer"}, "values": {"type": "array", "items": {"type": "array"}}}},
 "annotations": {"readOnlyHint": false, "destructiveHint": true},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

Dos de los cinco campos obligatorios no tienen nada que ver con la edición. expected_version convierte la escritura en un compare-and-swap: solo se aplica si la Note sigue en la versión que leyó el agente. idempotency_key hace que un reenvío no tenga efecto. Las otras escrituras de Notes, create_note_tab y add_note_source, exigen el mismo par. Las lecturas no: list_note_tabs, read_note_tab, read_sheet_range (como máximo 100 por 100 celdas) y list_note_attachments son todas readOnlyHint: true con osfoundry:read.

A continuación, lo que aporta ese contrato, medido sobre una reconstrucción. La comprobación de versión es solo la mitad. La otra mitad es lo que hace el agente cuando lo rechazan.

¿Por qué rechazar una escritura obsoleta en lugar de fusionarla?

replace_text envía el texto completo de una pestaña. Si Claude leyó la versión 7, una persona guardó la versión 8 y ahora Claude envía su texto, el servidor tiene dos documentos completos y le falta el ancestro común. No puede saber si Claude quería borrar el párrafo nuevo de la persona o si simplemente nunca lo vio. Con last-writer-wins se elige la respuesta equivocada sin que nadie se entere. Rechazar es la única respuesta que no adivina.

Eso es concurrencia optimista. Nadie mantiene un bloqueo mientras un modelo piensa durante veinte segundos. Cada escritura indica en qué versión se basa, y el servidor solo hace el intercambio si esa versión sigue siendo la actual:

UPDATE notes SET version = :new WHERE id = :note AND version = :expected;  -- 0 rows → conflict

La app de escritorio de osFoundry hace lo mismo desde el lado humano. En apps/web/src/screens/notes/context/NotesContext.tsx, guardar una Note es un PATCH /notes/:id que lleva expected_updated_at (la última revisión del servidor que vio el editor) y, después de una escritura Connected, un expected_version que connected-note-save-guard.ts guarda en localStorage para que una recarga no lo borre. Si el guardado falla, el editor conserva el contenido de la persona como borrador local y muestra un error de sincronización. Los dos editores escriben de forma condicional.

¿Qué debe hacer el agente cuando lo rechazan?

Hay dos reacciones plausibles, y solo una funciona:

Volver a leer la pestaña, aplicar de nuevo el cambio previsto sobre el contenido actual y escribir con la versión nueva.
Volver a leer solo la versión y reenviar el mismo payload.

La segunda pasa la comprobación y aun así sobrescribe a la persona, porque el payload se calculó a partir del texto antiguo. La comprobación no puede verlo. Una versión solo demuestra que has visto el número de versión más reciente, no que hayas usado su contenido.

La reconstrucción

Aquí no se ejecuta ningún binario de Claude. notes_store.py implementa list_note_tabs, read_note_tab, read_sheet_range, edit_note_tab (replace_text, sheet_set_range) y create_note_tab sobre sqlite en modo WAL, con los mismos nombres de herramientas y de argumentos que en producción. Cada escritura se ejecuta dentro de BEGIN IMMEDIATE: consulta la tabla de idempotencia, compara la versión, aplica el cambio, incrementa la versión y guarda el resultado, todo en una sola transacción. race.py arranca dos hilos, cada uno con su propia conexión: un "Claude" guionizado y una persona guionizada. Cada uno hace leer → pensar → escribir, 100 veces. El tiempo de pensar está reducido: 20–80 ms para Claude y 5–40 ms para la persona, de modo que la ventana entre lectura y escritura del agente es la más larga, como con un modelo real. Cada escritura añade una línea única (claude-17, human-42), así que al final cada línea que falta es una actualización perdida que se puede contar. Python 3.9.6, Apple M1, semillas 1–5.

La ruta de escritura, sin la fontanería de sqlite:

def _guarded(self, note_id, tab_id, expected_version, idempotency_key, apply):
    db.execute("BEGIN IMMEDIATE")
    hit = db.execute("SELECT result FROM idem WHERE key=?", (idempotency_key,)).fetchone()
    if hit:
        return {**json.loads(hit[0]), "replayed": True}
    current = tab_version if self.check == "tab" else note_version
    if self.check != "none" and expected_version != current:
        return {"error": "version_conflict", "current_version": current}
    result = apply(db)                       # replace_text / sheet_set_range / new tab
    # bump version, store (key, result), COMMIT

Y el bucle del agente, con el interruptor de política:

r = s.edit_note_tab("note-1", tab, tab_now["version"], uuid.uuid4().hex, **payload)
while "error" in r:
    fresh = s.read_note_tab("note-1", tab)
    if policy == "reapply":
        payload["text"] = fresh["data"] + "\n" + line   # redo the change on what's there now
    tab_now = fresh                                      # refresh_version keeps the old text
    r = s.edit_note_tab(...)

Un intento con conflicto recibe una idempotency key nueva. La clave identifica una escritura prevista sobre una base concreta. Tras un rechazo, la escritura que se vuelve a aplicar es otra escritura.

¿Cuántas actualizaciones se pierden sin la comprobación?

Cinco ejecuciones, 100 ediciones por editor en cada una, 1,000 líneas previstas en total por fila:

Protección de escritura	Agente ante un conflicto	Líneas perdidas	Perdidas: Claude / persona	Conflictos: Claude / persona	Máx. intentos
ninguna	—	300	125 / 175	0 / 0	1
versión de la Note	relee y vuelve a aplicar	0	0 / 0	219 / 133	2
versión de la Note	relee la versión y reenvía el texto antiguo	304	117 / 187	213 / 136	3

Sin comprobación desapareció el 30% de todas las ediciones, y la persona perdió más que Claude. Como el agente piensa más tiempo, sus escrituras se basan en lecturas más antiguas y sobrescriben más. Con la comprobación y volviendo a aplicar el cambio no se perdió nada. El 41–48% de las escrituras de Claude necesitaron un segundo intento, nunca un tercero. La media fue de 1.41–1.48 intentos para Claude y 1.24–1.30 para la persona. Todas las ejecuciones tardaron 9.6–10.5 s de tiempo real fuera cual fuera el modo, porque domina el tiempo de pensar.

La tercera fila es la que hay que recordar. El servidor informó de más de 300 conflictos y no protegió nada. Una comprobación de versión obliga a volver a leer. No puede obligar a usar lo que se ha leído.

¿Cuesta algo la comprobación?

bench.py cronometra 2,000 llamadas secuenciales a edit_note_tab con un replace_text de 200 caracteres, tres repeticiones por modo. Mediana por escritura: 61.9–63.1 µs sin comprobación, 57.0–58.8 µs con la versión de la Note y 55.1–61.1 µs con una versión por pestaña. La comparación es una lectura indexada dentro de una transacción que ya está abierta de todos modos. La diferencia queda por debajo del ruido entre ejecuciones. El p99 (0.42–1.33 ms) es jitter del fsync de sqlite y no depende del modo.

¿Por qué la versión es de la Note y qué cuesta eso?

Las descripciones de las herramientas de osFoundry asocian una sola versión a toda la Note. create_note_tab dice "Use the version from list_note_tabs", el listado a nivel de Note. En la ruta de la app de escritorio que aplica las ediciones Connected (connected-note-application.ts), expected_version se compara con el updated_at de la Note. Así que una persona que escribe en la pestaña Sheet mueve la versión contra la que se comprueba la escritura de Claude en la pestaña de texto.

En la reconstrucción eso se puede medir. Se ejecuta race.py tabs con Claude editando la pestaña de texto y la persona escribiendo celdas en la pestaña Sheet, 3 ejecuciones, 100 ediciones cada una:

Alcance de la versión	Conflictos de Claude	Conflictos de la persona	Perdidas
Note	130 de 300 escrituras (43%)	87 de 300 (29%)	0
Pestaña	0	0	0

Los 217 conflictos son falsos, porque los dos editores nunca tocaron la misma pestaña. Cada uno cuesta una relectura y nada más. Una versión a nivel de Note da algo que una versión por pestaña no puede dar: cada escritura se comprueba contra todo lo que hay en la Note, así que un agente que leyó la Sheet para escribir el Brief no puede escribir un Brief basado en valores de la Sheet que han cambiado entretanto. Las versiones por pestaña eliminan los falsos conflictos y pierden justo esa garantía entre pestañas. Para un agente que lee una pestaña y escribe en otra, la versión gruesa es el valor por defecto más seguro.

¿Qué le hace un timestamp en milisegundos a una comprobación de versión?

Una versión basada en timestamp solo funciona si dos guardados no pueden producir la misma cadena. race.py fast baja el tiempo de pensar a cero, 2,000 ediciones por editor, 5 ejecuciones, y compara una versión truncada a milisegundos con un timestamp en microsegundos más un sufijo de 6 dígitos hexadecimales:

Formato de versión	Líneas perdidas (de 20,000)	Ejecuciones con pérdidas
milisegundos	136 (0.68%)	5 de 5
microsegundos + sufijo	0	0 de 5

Cuando dos escrituras hacen commit en el mismo milisegundo, la segunda recibe la misma versión que la primera. Un editor que leyó antes de la primera escritura pasa entonces la comprobación contra la segunda. osFoundry guarda las versiones de las Notes con la precisión completa de los timestamps de PostgreSQL. Si construyes lo tuyo, usa un contador o un timestamp con desempate.

¿Por qué crear necesita su propia clave?

create_note_tab no reemplaza nada, así que una comprobación de versión por sí sola no puede evitar duplicados. La llamada repetida es una pestaña nueva sobre la versión nueva. race.py create crea 50 pestañas Sheet perdiendo el 30% de las respuestas, de modo que el cliente reintenta como haría un host tras un timeout:

	Llamadas enviadas	Pestañas creadas	Duplicados
sin clave, 3 ejecuciones	71 / 61 / 63	71 / 61 / 63	21 / 11 / 13
misma clave al reintentar	71 / 61 / 63	50 / 50 / 50	0

Con la clave, el reintento devuelve el primer resultado, incluido el ID de su pestaña, así que el siguiente edit_note_tab del agente apunta a la pestaña que existe. Es la línea "A repeated idempotency key returns the first tab" de la descripción de la herramienta en osFoundry.

Si lo montas tú mismo

Exige expected_version en todas las herramientas de escritura, en el esquema, no como campo opcional. Una comprobación opcional se salta la primera vez que un modelo va con prisa.
Devuelve el conflicto como un resultado normal de la herramienta con el que el modelo pueda actuar, y di en la descripción de la herramienta qué hacer: volver a leer y rehacer el cambio. Tus instrucciones son el único sitio donde puede vivir la regla de "vuelve a aplicar, no te limites a actualizar la versión".
Elige el alcance de la versión a propósito. Las versiones por documento dan falsos conflictos y protegen las lecturas entre pestañas. Las versiones por pestaña evitan los falsos conflictos y pierden esa protección.
Haz que las versiones no puedan colisionar: un contador, o un timestamp con precisión completa y desempate. Nunca un timestamp redondeado a milisegundos.
Protege las creaciones y los appends con una idempotency key que identifique una intención sobre una base. Guarda la clave y el resultado en la misma transacción que la escritura.
Protege también el editor humano. Si solo se comprueban los conflictos del agente, una pestaña del navegador desactualizada puede seguir sobrescribiendo al agente.

La definición breve de osFoundry del protocolo que hay debajo está en su entrada del glosario sobre MCP. Cómo guarda y restaura estados anteriores de una Note se explica en la página de versiones de Notes.

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

BBT — Sat, 07 Nov 2026 14:57:37 +0000

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.

Cómo osFoundry encuentra tus sesiones de Claude Code y Codex en disco, recreado en Python

BBT — Sat, 07 Nov 2026 14:41:18 +0000

~/.claude/projects/-Users-alex-code-shop-api/c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58.jsonl
~/.claude/projects/-Users-alex-code-shop-api/c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58/subagents/agent-<id>.jsonl
~/.codex/state_5.sqlite                      -> table threads (id, rollout_path, cwd, git_branch, title, …)
~/.codex/sessions/2026/11/04/rollout-2026-11-04T10-00-00-<thread id>.jsonl

$ claude --resume c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58
$ codex resume 019a2f1c-7d0e-7b31-9c4e-5a1f0e2d8b63

Ese es todo el contrato entre las CLI y un selector de sesiones. Claude Code y Codex guardan cada uno sus sesiones en archivos normales dentro de tu carpeta personal, y cada uno acepta un id para reanudar una. La pantalla External agents de la app de escritorio de osFoundry es un lector montado sobre esos archivos (Rust, runtime/session_inventory.rs y runtime/external_sessions.rs). Lista sesiones de doce apps, busca por título, carpeta, rama, app e id, y lanza en una terminal el comando de reanudación correcto.

A continuación tienes la parte de Claude Code y Codex, recreada como un script de Python de 150 líneas y ejecutada contra las carpetas de sesiones reales del Mac donde se escribió este artículo. En ningún punto del artículo se imprime contenido de las conversaciones. Cada número es un recuento, un tamaño o un tiempo.

¿Cómo se ve una sesión de Claude Code en disco?

Un archivo JSONL por sesión, con el id de la sesión como nombre, dentro de una carpeta que lleva el nombre del directorio de trabajo. El nombre de la carpeta es la ruta absoluta con cada carácter que no sea letra o dígito sustituido por -:

re.sub(r"[^A-Za-z0-9]", "-", cwd)   # /Users/alex/code/shop-api -> -Users-alex-code-shop-api

Comprobado con las 40 transcripciones de esta máquina: 40 de 40 carpetas siguen esa regla. La regla pierde información (my.app y my-app chocan, igual que / y .), así que nunca decodifiques el nombre de la carpeta. Lee cwd de los registros.

Los subagentes (Explore y compañía, de la herramienta Task) escriben sus propias transcripciones en <session id>/subagents/agent-<id>.jsonl. Aquí había 129. Nadie las reanuda como sesión, y osFoundry se salta cualquier archivo cuyo nombre base empiece por agent-.

Cada línea es un registro con un type. Contando los tipos en las primeras 400 líneas de cada uno de los 40 archivos:

type	registros	claves que importan para un índice
assistant	4,060	`requestedModel`, `effort`, `gitBranch`, `message.model`
attachment	3,197	`cwd`, `gitBranch`
user	2,469	`cwd`, `gitBranch`, `permissionMode`, `isSidechain`, `message.content`, `entrypoint`
custom-title	922	`customTitle`
agent-name	827	`agentName`
system, mode, queue-operation, file-history-, api-request, …	2,000+	no hacen falta

Los registros de conversación (user, assistant, attachment, system) llevan todos sessionId, cwd, gitBranch, timestamp y version. message.content es o un string o una lista de bloques; en esas líneas los tipos de bloque fueron tool_result 2,261, tool_use 2,223, thinking 1,224 y text 754. El título viene de un registro custom-title o, en las versiones que lo escriben, de un registro ai-title con aiTitle. Aquí todos los archivos tenían custom-title y ninguno ai-title, así que lee los dos.

¿Por qué no parsear cada archivo entero?

Porque son grandes. Las 40 transcripciones de primer nivel suman aquí 19.4 GB. La mediana es de 168 MB, el más grande pesa 2.07 GB y el percentil 90 está en 1.94 GB.

Pasar el archivo mediano por json.loads línea a línea tardó 0.61 s (11,558 líneas, unos 279 MB/s en un Mac con Apple Silicon, con la caché de páginas caliente). A ese ritmo, parsear los 40 completos llevaría unos 70 s, antes de haber mostrado nada.

Los datos que necesita una lista están en los dos extremos del archivo. Medido en los 40:

el primer registro con cwd estaba como muy tarde en la línea 2 (mediana 2)
el primer gitBranch y el primer registro user: como muy tarde en la línea 2
había un registro de título dentro de los últimos 512 KiB en 40 de 40 archivos
ninguna de las primeras 80 líneas pasaba de 256 KiB

Así que el índice lee las primeras 80 líneas y los últimos 512 KiB. Es lo mismo que hace osFoundry: HEAD_LINES = 80 con un límite de 256 KiB por línea en session_inventory.rs, y SETTINGS_TAIL = 512 * 1024 en external_sessions.rs, que se lee para sacar el último modelo, effort, modo de aprobación y rama. Leer cabeza y cola de los 40 archivos tardó 86 ms.

HEAD_LINES, LINE_CAP, TAIL_BYTES = 80, 256 * 1024, 512 * 1024


def head(p, n=HEAD_LINES):
    out = []
    with open(p, "rb") as f:
        for _ in range(n):
            line = f.readline(LINE_CAP + 1)
            if not line:
                break
            if len(line) > LINE_CAP:          # a pasted file or image: skip the rest of it
                while line and not line.endswith(b"\n"):
                    line = f.readline(1 << 20)
                continue
            out.append(line)
    return out


def tail(p, nbytes=TAIL_BYTES):
    with open(p, "rb") as f:
        f.seek(0, 2)
        size = f.tell()
        f.seek(max(0, size - nbytes))
        lines = f.read().split(b"\n")
    return lines[1:] if size > nbytes else lines   # first piece is a cut line

El readline con límite es importante. Un turno de usuario con una imagen pegada es una sola línea de varios megas, y un simple for line in f la cargaría entera en memoria solo para tirarla.

¿Qué campos necesita de verdad un selector?

Cinco, más una fecha: app, id, carpeta, rama y título. La cabeza da cwd, el primer gitBranch y un título de reserva sacado del primer mensaje real del usuario (que no sea sidechain ni empiece por <, que es como empiezan los envoltorios de comandos y hooks). La cola lo sobrescribe con el título y la rama más recientes, porque una sesión larga suele sobrevivir a la rama en la que empezó.

def claude_sessions():
    for proj in sorted((CLAUDE / "projects").glob("*/")):
        for p in proj.glob("*.jsonl"):
            if p.stem.startswith("agent-"):           # sub-agent transcript, not resumable
                continue
            st = p.stat()
            cwd = branch = title = None
            for v in records(head(p)):
                cwd = cwd or v.get("cwd")
                branch = branch or (v.get("gitBranch") or None)
                if title is None and v.get("type") == "user" and not v.get("isSidechain"):
                    t = (first_text((v.get("message") or {}).get("content")) or "").strip()
                    if t and not t.startswith("<"):
                        title = t[:80]
                if cwd and branch and title:
                    break
            for v in records(tail(p)):                 # newest wins: titles, branch moves
                for k in ("customTitle", "aiTitle"):
                    if v.get(k):
                        title = v[k][:100]
                branch = v.get("gitBranch") or branch
            yield {"app": "claude-code", "id": p.stem, "cwd": cwd, "branch": branch,
                   "title": title, "mtime": int(st.st_mtime * 1000), "bytes": st.st_size}

records() es json.loads por línea, saltándose las líneas rotas (la primera línea de una lectura de cola sale cortada por la mitad). first_text() devuelve el contenido si es string, o el primer bloque text. La fecha de último uso es el mtime del archivo, que también es lo que usa osFoundry para ordenar.

¿Dónde guarda Codex esos mismos datos?

Codex escribe un rollout por sesión en un árbol por fechas, ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<thread id>.jsonl, y guarda los archivados en ~/.codex/archived_sessions/. Aquí: 10 rollouts (28.5 MB) y 2 archivados. La primera línea de cada rollout es un registro session_meta cuyo payload tiene id, cwd, originator, source, cli_version, model_provider, timestamp y, en algunas versiones, git.branch. El resto son registros event_msg, response_item (con tipos de payload message, function_call, function_call_output, reasoning, custom_tool_call, …), turn_context y compacted.

Codex además mantiene un índice, así que ni siquiera tienes que abrir los rollouts. ~/.codex/state_<n>.sqlite tiene una tabla threads; aquí es state_5.sqlite, con 43 columnas y 12 filas, entre ellas id, rollout_path, cwd, git_branch, title, model, reasoning_effort, approval_mode, sandbox_policy, source, archived y updated_at_ms. Puede haber más de un archivo state_<n>; codex_state_db en osFoundry coge el n más alto, y el script hace lo mismo. Las filas cuyo source es un objeto JSON son hilos de subagentes; sáltatelas.

def codex_sessions():
    db = codex_db()
    if db:
        con = sqlite3.connect(f"file:{db}?mode=ro&immutable=1", uri=True)
        q = ("SELECT id, cwd, git_branch, title, COALESCE(updated_at_ms, updated_at*1000), source "
             "FROM threads ORDER BY 5 DESC LIMIT 300")
        for id_, cwd, br, title, ms, source in con.execute(q):
            if (source or "").startswith("{"):        # sub-agent thread
                continue
            yield {"app": "codex", "id": id_, "cwd": cwd, "branch": br,
                   "title": (title or "")[:100] or None, "mtime": ms or 0, "bytes": None}
        return
    for p in (CODEX / "sessions").glob("*/*/*/rollout-*.jsonl"):
        v = next(records(head(p, 1)), {})
        if v.get("type") != "session_meta":
            continue
        pl = v.get("payload", {})
        yield {"app": "codex", "id": pl.get("id"), "cwd": pl.get("cwd"),
               "branch": (pl.get("git") or {}).get("branch"), "title": None,
               "mtime": int(p.stat().st_mtime * 1000), "bytes": p.stat().st_size}

Algo que costó un segundo intento: abrir la base de datos solo con ?mode=ro falló aquí con unable to open database file. Añadir immutable=1 lo resolvió. Immutable le dice a SQLite que el archivo no va a cambiar mientras esté abierto, así que se salta el bloqueo y los archivos -shm; para un índice que es una instantánea no pasa nada, y te permite leer una base de datos que la app tiene abierta. osFoundry abre el índice de Codex con SQLITE_OPEN_READ_ONLY, y usa una apertura con immutable=1 para bases de datos que otra app puede tener abiertas en escritura.

¿Qué tan rápido va con carpetas reales?

$ python3 sessidx.py build          # four runs, same Mac, real ~/.claude and ~/.codex
52 sessions  claude 154 ms  codex 3 ms
52 sessions  claude 80 ms  codex 2 ms
52 sessions  claude 83 ms  codex 2 ms
52 sessions  claude 107 ms  codex 4 ms

52 sesiones (40 de Claude Code, 12 de Codex), todas con carpeta y título, y las 40 de Claude Code con rama. La primera ejecución es la más fría; las demás fueron en caliente. El archivo de índice ocupa 11,480 bytes. Frente a un parseo completo de 70 s, 80 a 150 ms es la diferencia entre una lista que se abre al instante y otra con spinner.

La búsqueda es entonces una comprobación de substring sobre cinco campos, los mismos que usa matchesQuery de osFoundry en lib/external-sessions.ts:

def matches(r, q):
    q = q.strip().lower()
    return not q or any(q in str(v).lower() for v in (r["title"], r["cwd"], r["branch"], r["app"], r["id"]) if v)

Sobre una carpeta personal falsa con la misma estructura (datos de ejemplo, no las sesiones reales):

$ SESSIDX_HOME=./fx python3 sessidx.py find checkout
codex       019a2f1c  test/checkout-e2e    -
claude-code c5e1a7b2  fix/checkout-retry   Fix double charge on checkout retry
$ SESSIDX_HOME=./fx python3 sessidx.py resume c5e1
cd /Users/alex/code/shop-api && claude --resume c5e1a7b2-9d40-4f3e-8b16-2a7c0e9d4f58

Buscar dentro del texto de los mensajes significaría leer los 19.4 GB, o montar un índice de texto completo de todo lo que alguna vez pegaste en un agente. Buscar por carpeta y rama encuentra la sesión por el nombre del proyecto, que es lo que recuerdas de todas formas.

¿Qué añade una reanudación segura?

Imprimir claude --resume <id> es lo fácil. Lo que osFoundry añade alrededor (plan_command y el plan de lanzamiento en external_sessions.rs, más las comprobaciones que hace la pantalla antes de abrir la terminal) vale la pena copiarlo:

Ejecutar en la carpeta registrada, y negarse si ya no existe en lugar de reanudar en otro sitio.
Comparar la rama registrada con git -C <cwd> rev-parse --abbrev-ref HEAD. Si no coinciden, avisar y preguntar; nunca hacer checkout.
Mantener el modelo (--model, en Codex -m) y el effort (--effort, en Codex -c model_reasoning_effort="…").
Mantener un modo de aprobación registrado solo si es al menos tan estricto como el predeterminado de la CLI. En Claude Code eso es default o plan; en Codex, aprobación untrusted u on-request, y sandbox read-only o workspace-write. Cualquier cosa más permisiva se retiene salvo que la persona lo active para ese lanzamiento concreto.

El sessidx.py completo son las tres piezas de arriba más unas 30 líneas de pegamento (variables de entorno para cambiar las carpetas personales, salida JSON, y los subcomandos find y resume). En el Mac usado aquí no hay binario de claude ni de codex, así que la línea de reanudación se imprime, no se ejecuta.

Si lo montas tú

Trata los archivos como la API: solo lectura, nunca escribas junto a ellos y nunca abras los archivos de autenticación de las CLI para sacar un nombre de cuenta.
Lee cabeza y cola, no transcripciones enteras. Limita la longitud de línea para que una imagen pegada no te cueste su tamaño en memoria.
Saca cwd de los registros, no del nombre de carpeta escapado.
Usa preferentemente el state_<n>.sqlite de Codex (el n más alto) en vez de recorrer el árbol por fechas, y ábrelo como immutable si la app puede tenerlo abierto.
Excluye de la lista las transcripciones de subagentes (agent-*.jsonl, hilos con source JSON); nadie las reanuda directamente.
Decide de antemano qué puede cambiar una reanudación. Un valor seguro por defecto: carpeta sí, modelo sí, aprobaciones más permisivas solo si se piden, rama nunca.

La vista Sessions de los propios agentes de osFoundry trabaja con otra fuente; está descrita en la página de sesiones de agentes de osFoundry.

Cómo conectar un chat de Claude a tus proyectos de osFoundry con un conector personalizado

BBT — Sat, 07 Nov 2026 13:42:37 +0000

Al terminar, una conversación normal de Claude en claude.ai podrá abrir las Notes, las bases de conocimiento y los Records de uno de tus proyectos de osFoundry, responder a partir de ellos y publicar en el canal de discusión de ese proyecto. Con tu aprobación, también podrá editarlos. Sigues con tu sesión de Claude como siempre. En cada llamada a una herramienta, osFoundry decide qué puede tocar ese chat, y cada llamada queda registrada en osFoundry en el Recent activity de la conexión. ChatGPT se conecta igual, con la misma dirección de servidor.

Quién hace qué

	Lado de Claude	Lado de osFoundry
Inicio de sesión	Tu cuenta de Claude, sin cambios	Tu cuenta de osFoundry aprueba la conexión una vez, para un workspace
Qué ejecuta el modelo	Claude, en el chat que ya usas	Nada. En este camino no hay modelo ni clave de proveedor
Dónde se ejecutan las herramientas	Claude envía la llamada a la herramienta	`api.osfoundry.io` la ejecuta y antes comprueba el acceso
Qué puede alcanzar	Lo que devuelva el servidor	Los proyectos a los que añadiste la conexión, más los canales a los que la invitaste
Aprobaciones	El aviso de permisos de herramientas del propio Claude	Los cambios en GitNest y Room esperan en "Needs your approval"
Dónde se quedan los datos	La respuesta vive en tu chat de Claude	Las Notes, los records y los artículos se quedan en osFoundry. Lo que es solo local nunca sale del dispositivo

Configuración

1. Crea la conexión en osFoundry

En osFoundry, haz clic en el icono de la llave en la cabecera y abre la pestaña Connected. El panel se titula "Connected agents" y muestra en qué workspace estás. En "Connect in three steps":

Assistant: elige Claude
Display name: cualquier nombre que reconozcas después, por ejemplo Claude research
Haz clic en Add assistant (añadir asistente)

La nueva conexión muestra "Setup pending. This assistant cannot read or change anything yet." Copia la Server address con el botón Copy que tiene al lado:

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

Ejemplo: La pestaña Connected después de Add assistant, con la dirección del servidor y una conexión pendiente

2. Añádela a Claude como conector personalizado

En Claude, abre Customize → Connectors y añade un conector personalizado con esa URL. En un plan Team o Enterprise, primero la añade un propietario de la organización en Organization settings → Connectors, y luego cada miembro se conecta. Los pasos de Anthropic para conectores MCP remotos están en la guía de conectores personalizados de Claude.

Al hacer clic en Connect, Claude encuentra por sí solo el inicio de sesión de osFoundry. No pegas ningún client ID ni ninguna clave.

3. Aprueba un workspace

El navegador llega a https://osfoundry.io/external-assistant-authorize, una página titulada "Connect an agent". Muestra el cliente del asistente y el host al que vuelve, y después pide:

Workspace to connect: un solo workspace. Un segundo workspace necesita su propia conexión.
Requested capabilities, en lenguaje claro: "Read supported resources in projects you add", "Change supported resources where you have edit access", "Run sessions where you grant a runner role".
Connection: elige "Use pending: Claude research" para que se vincule a la conexión del paso 1, o deja "Create a new connection".
Marca "I approve connecting this assistant to " y luego Connect.

Vuelves a Claude. La conexión está activa, pero todavía no ve nada. Una conexión nueva empieza con cero proyectos.

4. Añádela a un proyecto

De vuelta en icono de la llave → Connected, selecciona la conexión. Ahora dice "Connected." En Projects, elige un proyecto y haz clic en Add to project.

Ejemplo: La conexión añadida a un proyecto, con su chat vinculado debajo

Esto da acceso al contenido sincronizado compatible de ese proyecto: Notes, bases de conocimiento, canales de Record, Rooms en la nube, los repositorios de GitNest asignados a él y el canal de discusión del proyecto. El contenido que añadas al proyecto más adelante también se incluye. Los canales de Message normales van aparte. Usa Message channels → Choose a Message channel → Invite para cada uno en el que el chat deba leer y responder.

La sección Tools dice "All supported tools are on by default." Desmarca las que no quieras que tenga esta conexión y haz clic en Save tools.

Ejemplo: La lista de Tools de una conexión de Claude, todas activadas por defecto

5. Actívala en el chat

En una conversación de Claude, abre el menú + → Connectors y activa el conector de osFoundry. Después, pide lo que necesites en lenguaje normal.

Una ejecución real

El prompt y la respuesta de abajo son contenido de ejemplo de un proyecto de demostración. Los nombres de las herramientas y de los argumentos son los que el servidor en producción anuncia en tools/list. En claude.ai, las llamadas aparecen bajo el nombre del conector. Si añades la misma URL a Claude Code como osfoundry, las mismas herramientas aparecen como mcp__osfoundry__list_project_resources, etc.

Ejemplo

Tú: Usando osFoundry, ¿qué sigue abierto en la checklist del lanzamiento Q3?
    Revisa la KB de soporte por si algo la contradice y luego marca
    el record "pricing page" como Ready.

Claude → list_granted_resources {}
       ← 1 proyecto conectado: "Launch Q3" (workspace)
Claude → list_project_resources {"project_id": "…", "resource_type": "note", "search": "checklist"}
       ← Note "Q3 launch checklist"
Claude → list_note_tabs {"note_id": "…"}
       ← pestañas: Note (texto), Sheet "Owners"
Claude → read_note_tab {"note_id": "…", "tab_id": "…"}
       ← 9 elementos, 3 sin marcar
Claude → search_knowledge_base {"knowledge_base_id": "…", "query": "refund window"}
       ← artículo "Refund policy" (actualizado hace 2 días)
Claude → read_record_item {"record_channel_id": "…", "item_id": "…"}
       ← "pricing page", status Draft, version …
Claude → edit_record_item {"record_channel_id": "…", "item_id": "…",
                           "values": {"status": "Ready"},
                           "expected_version": "…", "idempotency_key": "…"}
       [Claude te pide permitir esta llamada → Allow]
       ← guardado, nueva version …

Claude: Hay tres elementos abiertos: la fecha de embargo de prensa,
        la traducción de las FAQ y la línea de reembolsos de la
        pricing page. La checklist dice 14 días; el artículo de la KB
        "Refund policy" dice 30. He marcado el record de la pricing
        page como Ready.

Dos detalles de esa transcripción son intencionados. edit_record_item necesita la version que devolvió read_record_item, así que un record que haya cambiado entretanto se rechaza en lugar de sobrescribirse. Un idempotency_key repetido devuelve el primer resultado, así que una llamada reintentada no escribe dos veces.

Dónde está el límite

osFoundry no puede abrir tus chats de Claude. La conexión MCP permite que Claude llame a herramientas de osFoundry cuando él lo decide. osFoundry no tiene ninguna API en la dirección contraria para listar, leer o iniciar una conversación personal. La herramienta que vincula un chat a un proyecto (link_current_chat) recibe una etiqueta que el propio chat declara, y osFoundry la trata como una pista de enrutamiento, no como una identidad verificada. Por la misma razón, Claude no recibe notificaciones en segundo plano de osFoundry. Actúa cuando abres la conversación y le pides algo.

Los datos solo locales se quedan en local. El propio servidor lo dice en su respuesta a initialize: "Local-only data is unavailable to cloud clients." Las Rooms locales, las sesiones locales de Graph y el contenido que nunca se sincronizó no son visibles para la conexión. Compartir sesiones de Graph del escritorio es un interruptor aparte en la misma pestaña, y la app de escritorio tiene que estar abierta y con la sesión iniciada.

El acceso se comprueba en cada llamada, no en cada inicio de sesión. Cada llamada se contrasta con el estado de la conexión, su workspace, la membresía actual del proyecto, en qué proyecto está el elemento en ese momento y tu propio rol sobre ese elemento. Mueve una Note a otro proyecto, quita el proyecto o haz clic en Revoke connection, y la siguiente llamada se rechaza. Las ediciones también requieren que tú, la persona que aprobó la conexión, sigas teniendo permisos de edición.

Algunas escrituras se convierten en propuestas. El trabajo en GitNest, los change sets, las importaciones de archivos, los pull requests y las instalaciones de apps en Rooms pasan por herramientas propose_…. Esperan en la pestaña Connected, en "Needs your approval", donde ves el repositorio o la Room de destino y los archivos antes de elegir Approve o Decline. Claude nunca recibe tu token del proveedor de Git ni ningún valor secreto.

Los canales de Message necesitan invitación. Estar en un proyecto solo abre el canal de discusión de ese proyecto. Cualquier otro canal necesita un Invite explícito, y un canal privado necesita que lo invite su propietario.

Siguiente paso

Añade una base de conocimiento al mismo proyecto y hazle a Claude una pregunta que normalmente responderías con ella, por ejemplo "¿Qué dice nuestra KB sobre reembolsos, con el nombre del artículo?". search_knowledge_base devuelve el ID del artículo y cuándo se actualizó por última vez, así que puedes comprobar la fuente. Cómo se organizan las bases de conocimiento de osFoundry se explica en la página de bases de conocimiento.

¿Cómo encuentra un conector personalizado de Claude el servidor OAuth de osFoundry y por qué se comprueba el acceso en cada llamada?

BBT — Fri, 06 Nov 2026 10:30:52 +0000

Esto es lo que recibe un cliente MCP remoto cuando llama a una herramienta de osFoundry sin token. La petición se hizo con curl desde un Mac en Tokio el 2026-11-06:

$ curl -s -D - -X POST https://api.osfoundry.io/api/v1/external-mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
         "params":{"name":"list_project_resources","arguments":{}}}'

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"

{"jsonrpc":"2.0","id":3,"result":{"isError":true,
  "content":[{"type":"text","text":"Authentication required"}],
  "_meta":{"mcp/www_authenticate":["Bearer resource_metadata=\"https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp\", ..."]}}}

Con esa única cabecera, el conector personalizado de Claude, o la conexión MCP del modo desarrollador de ChatGPT, encuentra la página de inicio de sesión. El usuario solo pega la URL. Todo lo que sigue sale de peticiones sin autenticar al endpoint en producción, más una pequeña reconstrucción en Python, ejecutada en local, que mide lo que un curl no puede enseñar: qué pasa con el acceso después de iniciar sesión.

¿Qué ve el cliente antes de tener un token?

Tres llamadas, tres respuestas distintas:

Petición	Estado	Qué devuelve
`initialize`	200	protocolo `2025-06-18`, servidor `osfoundry 0.1.0`, más instrucciones
`tools/list`	200	59 herramientas, 45,368 bytes
`tools/call`	401	`WWW-Authenticate` apuntando a los metadatos del recurso
`GET` sobre el endpoint	405	no hay stream SSE por GET

El handshake y el catálogo de herramientas son públicos. Solo llamar a una herramienta exige token. Así el host puede enseñar al usuario qué herramientas existen antes de que nadie inicie sesión. Nada del catálogo son datos de usuario, y el texto de instructions en initialize es genérico:

Use list_granted_resources first. Every Note edit must use the exact tab ID.
Local-only data is unavailable to cloud clients.

Cada herramienta de tools/list declara el scope OAuth que necesita y si solo lee:

{"name": "edit_record_item",
 "annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

De las 59 herramientas, 30 necesitan osfoundry:read y llevan readOnlyHint: true, 26 necesitan osfoundry:write y 3 necesitan osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). Un host puede usar readOnlyHint para decidir qué llamadas piden confirmación al usuario.

¿Adónde le manda el 401?

resource_metadata sigue la RFC 9728 (OAuth Protected Resource Metadata). El sufijo well-known va justo después del host, con la ruta del recurso añadida detrás. No se añade al final de la URL del recurso:

GET /.well-known/oauth-protected-resource/api/v1/external-mcp   200
GET /.well-known/oauth-protected-resource                       200 (same document)
GET /api/v1/external-mcp/.well-known/oauth-protected-resource   404

{"resource": "https://api.osfoundry.io/api/v1/external-mcp",
 "authorization_servers": ["https://api.osfoundry.io"],
 "scopes_supported": ["osfoundry:read", "osfoundry:write", "osfoundry:run", "osfoundry:models"]}

Si escribes un cliente a mano, ese 404 es el primer error que vas a cometer. Lee la URL de la cabecera en lugar de construirla tú.

¿Qué dice de sí mismo el servidor de autorización?

/.well-known/oauth-authorization-server (RFC 8414):

{"issuer": "https://api.osfoundry.io",
 "authorization_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/authorize",
 "token_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/token",
 "registration_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/register",
 "grant_types_supported": ["authorization_code", "refresh_token"],
 "token_endpoint_auth_methods_supported": ["none"],
 "code_challenge_methods_supported": ["S256"],
 "authorization_response_iss_parameter_supported": true}

Léelo como una cadena de decisiones. Hay un registration_endpoint, así que el host puede registrarse solo (registro dinámico de clientes) y el usuario nunca toca un client ID. La autenticación en el token es none, así que el host es un cliente público sin client secret, y lo que ata el código al cliente que lo pidió es PKCE con S256. iss en la respuesta de autorización evita confusiones cuando un host habla con varios servidores de autorización.

El paso de autorización lleva el navegador a la página de consentimiento de osFoundry, https://osfoundry.io/external-assistant-authorize. Ahí el usuario elige exactamente un workspace y marca "I approve connecting this assistant to …" (apruebo conectar este asistente a …). La aprobación nombra un workspace y nada más. Una conexión nueva no tiene proyectos. El propietario los añade después en la app (key icon → Connected → Add to project).

¿Por qué no basta con el scope?

Un scope se fija cuando se emite el token. osfoundry:write dice que la conexión puede hacer acciones de escritura. No dice qué Note, y no puede saber que esa Note se movió a otro proyecto hace diez minutos. Las notas de diseño de osFoundry enumeran lo que se vuelve a leer en cada llamada: estado de la conexión, workspace, pertenencia al proyecto, el proyecto actual y la ACL del recurso, pertenencia al canal o rol en la sesión, la herramienta y el scope OAuth. Además, la persona que aprobó la conexión tiene que seguir teniendo permisos de edición sobre el elemento. Quitar o reasignar algo "tiene efecto inmediato".

La alternativa es meter la lista de proyectos en el token, o en una caché indexada por el token, y fiarse de ella hasta que caduque. Es más barato de escribir. La reconstrucción de abajo implementa las dos cosas para poder medir la diferencia de comportamiento.

La reconstrucción

No hay ningún binario de Claude de por medio. client.py hace de host y server.py hace de servidor MCP. Los dos usan solo la biblioteca estándar, unas 280 líneas entre ambos, y se ejecutaron con Python 3.9.6 en un Apple M1. El servidor implementa initialize, tools/list y tools/call sobre JSON-RPC en HTTP plano, los dos documentos well-known, /authorize (la página de consentimiento se aprueba sola para un workspace) y /token con PKCE S256. Unas cuantas rutas /admin/* sustituyen a los clics del propietario en la pestaña Connected.

La comprobación que se ejecuta antes de cada herramienta:

def access(token_info, tool, note_id):
    if TOOL_SCOPE[tool] not in token_info["scopes"]:
        return "insufficient_scope"
    if CHECK == "token_only":                     # design B: trust issue-time state
        ok = note_id is None or NOTES[note_id]["project"] in token_info["projects_at_issue"]
        return None if ok else "not_in_project"
    conn = CONNECTIONS.get(token_info["connection"])
    if not conn or conn["status"] != "active":
        return "connection_revoked"
    if note_id is None:
        return None
    note = NOTES.get(note_id)
    if not note or note["workspace"] != conn["workspace"]:
        return "not_found"
    if (token_info["connection"], note["project"]) not in PROJECT_MEMBERS:
        return "not_in_project"
    return None

El cliente arranca sin token. Llama a una herramienta, recibe el 401, saca resource_metadata de WWW-Authenticate, descarga los dos documentos de metadatos, hace authorize y token con un verificador PKCE nuevo y luego recorre el escenario:

$ CHECK=per_call python3 server.py &  python3 client.py 8767
discovery: first call -> 401, metadata /.well-known/oauth-protected-resource/mcp, 5 round trips, 11.3 ms
1 fresh connection, no project yet           200 OK   []
2 after owner adds project A                 200 OK   ["note-a1"]
3 read note in A                             200 OK   "Q3 launch checklist"
4 read note in B (never added)               200 DENY not_in_project
5 write with a read-only token               403 DENY insufficient_scope
6 write with read+write token                200 OK   "saved"
7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 DENY not_in_project
9 same read after revoke                     200 DENY connection_revoked

El mismo cliente contra CHECK=token_only. Aquí el token lleva la lista de proyectos de su último refresco:

7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 OK   "Q3 launch checklist v2"
9 same read after revoke                     200 OK   "Q3 launch checklist v2"

Los pasos 1–7 son idénticos. El paso 7 sigue denegado en el diseño solo-token porque el proyecto de la nota se consulta en vivo. El diseño solo-token solo se queda desfasado en los datos que viven dentro del token. Los pasos 8 y 9 son los que le importan al propietario: quitó el proyecto, luego revocó la conexión, y el chat siguió leyendo. En el diseño solo-token eso dura hasta que caduca el token, que en esta reconstrucción es expires_in: 3600.

Las denegaciones se reparten en dos capas. Un scope que falta es un fallo a nivel de protocolo: 403 con error="insufficient_scope" y el scope necesario en WWW-Authenticate, para que el host pueda pedir más. Todo lo que tiene que ver con qué elemento está implicado es un resultado normal de herramienta con isError: true. Volver a autorizar no lo arreglaría, así que no tiene sentido decirle al host que lo intente.

¿Cuánto cuesta la comprobación en cada llamada?

Medido con time.perf_counter_ns() alrededor de access() dentro del servidor, 1,000 llamadas por ejecución (500 permitidas, 500 denegadas), en un Mac que además estaba ejecutando otros trabajos:

	access() mediana	access() p99	llamada a herramienta en loopback, mediana
comprobación por llamada, 6 ejecuciones	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
solo token, 3 ejecuciones	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 ejecuciones)

En memoria, la recomprobación se pierde en el ruido de una llamada HTTP por loopback. Un servidor real hace consultas a base de datos en lugar de comprobar pertenencia a un conjunto, así que su coste es mayor. Esta reconstrucción no puede medirlo, así que no se da ninguna cifra. Para hacerse una idea, el tramo de red hasta el endpoint en producción desde Tokio ronda los 500 ms a 800 ms por petición con urllib y una conexión TLS nueva cada vez (n=10 cada una: initialize mediana 790 ms, tools/list 816 ms, el tools/call con 401 565 ms, cada documento de metadatos unos 520–530 ms). Un conector no pierde el tiempo en la comprobación de acceso.

El descubrimiento en sí fueron 5 idas y vueltas HTTP en local: 401, metadatos del recurso, metadatos del servidor, authorize, token. Tardó 7.5–13.4 ms en siete ejecuciones y 34 ms una vez con el Mac ocupado. Contra el servidor en producción, los tres tramos GET/POST que puedes hacer sin credenciales suman aproximadamente 1.6 s en frío. El tramo de authorize espera a una persona de todos modos.

¿Por qué Claude puede llamar a osFoundry, pero osFoundry no puede abrir tus chats de Claude?

En este montaje quien llama es el host. Abre la conexión, lista las herramientas y decide cuándo llamar a una. El servidor responde. Nada en este montaje le da al servidor un acceso a las conversaciones del host. El plan de osFoundry lo dice en su tabla de capacidades: abrir o enumerar chats personales arbitrarios de ChatGPT/Claude es "No", con "No general host API is provided for this".

Eso condiciona las herramientas. Con link_current_chat, es el propio chat el que crea un enlace desde dentro. Su etiqueta la declara el propio chat, y osFoundry la usa para enrutar, no como identidad. El trabajo asignado a un chat de Claude enlazado espera hasta que el usuario abre ese chat y le pide que lo revise. ChatGPT tiene MCP Events para chats suscritos, y el plan de osFoundry lo trata como algo específico de ese host.

El lado del servidor es dueño de todas las decisiones sobre datos, porque es el único que conoce el estado actual de un proyecto. El lado del host es dueño de todas las decisiones sobre cuándo actuar y si preguntar al usuario. La comprobación en cada llamada es lo que permite que el servidor siga siendo correcto cuando esos dos lados se desincronizan.

Si lo montas tú

Pon resource_metadata en el WWW-Authenticate del 401 y sirve la RFC 9728 en /.well-known/oauth-protected-resource/<resource path>. Un cliente que construye la URL a mano puede equivocarse. La cabecera se lo ahorra a todos los clientes.
Decide qué es público antes del inicio de sesión. osFoundry expone initialize y tools/list y protege tools/call. Si las descripciones de tus herramientas filtran algo sobre los tenants, protege también tools/list.
Declara un scope y readOnlyHint por herramienta. Los hosts pueden construir con ellos las peticiones de confirmación, y un 403 insufficient_scope le da al host algo concreto que volver a pedir.
Mantén el token pequeño: quién, qué conexión, qué scopes. Vuelve a leer en cada llamada el workspace, la pertenencia al proyecto, el proyecto del recurso y el rol actual de quien aprobó, para que revocar y "mover a otro proyecto" funcionen en la siguiente llamada.
Devuelve las denegaciones sobre recursos como resultados de herramienta, no como 401/403. Otro token no va a arreglar "esta Note está en el proyecto B".
Haz que las escrituras lleven expected_version y una clave de idempotencia. Los hosts reintentan, y los modelos repiten llamadas.

La parte MCP de la especificación está en la página de autorización de MCP. La definición breve de osFoundry está en su entrada del glosario sobre MCP.