Esto es todo lo que el servidor MCP de osFoundry ofrece a un cliente que quiere enterarse de cuándo cambia algo. Ejecutado desde este Mac, sin token:
$ uv run --with tiktoken --with jsonschema python3 watch_sim.py
== Part 1: live wire, 8 calls each, ms ==
initialize HTTP 200 median 414.7 p90 757.8
tools/list HTTP 200 median 606.8 p90 716.7
resources/subscribe HTTP 200 median 450.6 p90 550.2
GET (stream) HTTP 405 median 423.9 p90 475.4
tools/call poll (no token) HTTP 401 median 322.0 p90 463.9
initialize capabilities: {"tools": {"listChanged": false}}
resources/subscribe -> {"code": -32601, "message": "Method not found"}
GET body -> ''
poll without token -> isError True | Authentication required
rate limit headers: limit 2000, reset in 61 s
Las tres vías de push están cerradas. initialize declara herramientas y nada más, con listChanged: false, así que ni siquiera la lista de herramientas avisará de un cambio. resources/subscribe devuelve "Method not found". Un GET a la URL MCP, donde un servidor Streamable HTTP abriría un stream del servidor al cliente, devuelve 405. Lo que queda es una única herramienta de solo lectura:
{"name": "poll_resource_events",
"description": "Resume from an event sequence for one granted channel, Note, knowledge base, record, or session.",
"inputSchema": {"properties": {
"resource_type": {"enum": ["message_channel", "note", "knowledge_base", "record_channel", "room",
"gitnest_repository", "agent_session", "team_session", "loop_session",
"graph_session"]},
"resource_id": {"type": "string"},
"after_sequence": {"type": "integer", "minimum": 0},
"limit": {"type": "integer", "minimum": 1, "maximum": 100}},
"required": ["resource_type", "resource_id"], "additionalProperties": false},
"annotations": {"readOnlyHint": true, "openWorldHint": false, "destructiveHint": false},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:read"]}]}
Un recurso "one granted", "resume from an event sequence". El resto del post trata de esas palabras, con el lado del cliente reconstruido en Python. Aquí no hay ningún binario de codex instalado, así que el script hace de cliente. El código del servidor de osFoundry no es público: las partes 1 y 2 son el servidor en vivo, y la parte 3 es una reconstrucción con sus propias formas de respuesta y tasas de actividad.
¿Por qué polling y no push, en el caso de Codex?
Codex CLI no es un daemon. Corre cuando lo ejecutas, hace un turno y termina o se queda esperándote. Un canal push necesitaría algo escuchando entre tus sesiones, y en un portátil muchas veces no hay nada. Un cursor de secuencia encaja con esa forma de trabajar: el cliente guarda un entero por recurso, vuelve cuando quiere y pregunta qué pasó después de ese número.
Los milisegundos de arriba están medidos desde Japón en un Apple M1, así que dicen más de la ruta que del servidor. Importa más la cabecera de rate limit. Las respuestas sin autenticar llevan X-RateLimit-Limit: 2000 con un reset unos 61 s más adelante. No se comprobó si un cliente con sesión iniciada tiene el mismo presupuesto, pero incluso consultar 30 recursos cada 30 s son 60 peticiones por minuto. Lo que limita a un vigilante hecho con Codex no es la carga del servidor, sino sus propios turnos: cada poll es una llamada a herramienta que el modelo tiene que hacer y leer.
¿Cómo descubre un cliente qué puede consultar?
Con dos llamadas, y los schemas dicen mucho del diseño:
list_granted_resources osfoundry:read ro=True required=[] props=[]
list_project_resources osfoundry:read ro=True required=['project_id', 'resource_type'] props=['project_id', 'resource_type', 'search', 'offset', 'limit']
poll_resource_events osfoundry:read ro=True required=['resource_type', 'resource_id'] props=['resource_type', 'resource_id', 'after_sequence', 'limit']
59 tools on server; these three = 591 of 12662 tokens (4.7%, cl100k_base)
poll_resource_events types: 10 | list_project_resources types: 9 | only pollable: ['graph_session']
list_granted_resources no acepta ningún argumento, y el schema cierra la puerta a añadir uno:
list_granted_resources no arguments ok
list_granted_resources project_id passed REJECT additionalProperties
Es el servidor diciéndole al cliente lo que tiene, no el cliente pidiendo algo. Las instrucciones de initialize empiezan con "Use list_granted_resources first." La respuesta son los proyectos añadidos a la conexión y los recursos concedidos de forma individual. En el cliente web (ExternalAssistantsPanel.tsx) corresponden a la sección Projects y a "Older individual access".
list_project_resources necesita un resource_type. No existe un listado de "todo lo que hay en este proyecto", así que un inventario completo es una llamada por tipo, nueve tipos, y más cuando un tipo tiene más de 50 elementos (limit máximo 50, paginado con offset). Su descripción añade la única excepción al acceso por proyecto: "Ordinary Message channels require a separate invitation."
graph_session se puede consultar pero no listar. Los Graphs viven en el escritorio del propietario y llegan a través de list_graph_sessions, y solo después de que el propietario los comparta desde la app de escritorio.
¿Por qué el cursor es del cliente y no del servidor?
osFoundry tiene los dos tipos. wait_for_messages, en la red de agentes, guarda un cursor por ti: "Without after_sequence it resumes where your last call stopped", y hace long polling con timeout_s de hasta 50. poll_resource_events no tiene ninguna de las dos cosas. timeout_s se rechaza y su descripción solo dice "resume from", así que el número lo aporta el cliente:
wait_for_messages props: ['after_sequence', 'timeout_s', 'limit'] timeout_s max 50 | poll_resource_events has timeout: False
poll_resource_events timeout_s 30 REJECT additionalProperties
Un cursor guardado en el servidor es cómodo para un solo oyente. Se rompe cuando dos clientes comparten conexión, que es justo lo que pasa cuando abres Codex en dos terminales con el mismo login. La reconstrucción hace pasar 600 eventos de canal por dos terminales que se turnan al azar para consultar:
two terminals, client cursor: A saw 600/600, B saw 600/600
two terminals, server cursor: A saw 305/600, B saw 295/600
Con un cursor por conexión en el servidor, cada terminal lo avanza en nombre de la otra y cada una ve más o menos la mitad. Con after_sequence en la petición, las dos lo ven todo y el servidor no guarda ningún estado por lector. Para el log de un recurso que varias herramientas pueden leer por separado, ese es el dueño correcto del cursor.
El schema no hace obligatorio after_sequence y tampoco dice qué significa omitirlo. No dependas de eso. Guarda el número y envíalo siempre.
¿Cuántas llamadas cuesta una página llena?
limit llega hasta 100. Después de una importación masiva, una nota puede tener cientos de eventos esperando. Vaciarlos significa volver a llamar desde la última secuencia hasta que una página llegue incompleta:
burst of 350 events, limit 100: 4 calls to drain, cursor ends at 350
burst of 350 events, limit 50: 7 calls to drain, cursor ends at 350
burst of 350 events, limit 20: 18 calls to drain, cursor ends at 350
Pide 100. En la reconstrucción, la respuesta ocupa 17 tokens con una página vacía y 41 con un evento, contados con cl100k_base. Son las formas de la reconstrucción, no las de osFoundry, pero el orden de magnitud basta para verlo: un poll vacío es barato de leer, así que el coste del polling está sobre todo en el número de turnos.
¿Cada cuánto debería Codex consultar 30 recursos?
La reconstrucción le da a un proyecto 30 recursos de los nueve tipos listables, con actividad desigual: 3 muy activos (un evento por minuto), 7 templados (uno cada 10 minutos) y 20 fríos (uno cada 2 horas). Esas tasas son una suposición. Simula una jornada de 8 horas con cinco semillas, sobre un reloj simulado:
every 30 s, all 30 calls/hour 3600 empty 94.7% seen late median 14.9 s p90 27.0 s max 30 s (1843 events/day)
every 5 min, all 30 calls/hour 360 empty 78.0% seen late median 150.9 s p90 271.1 s max 300 s (1843 events/day)
30 s, x2 when empty, cap 10 min calls/hour 502 empty 70.2% seen late median 34.9 s p90 206.4 s max 599 s (1843 events/day)
30 s, x2 when empty, cap 30 min calls/hour 420 empty 65.3% seen late median 35.6 s p90 238.4 s max 1799 s (1843 events/day)
server window for comparison: 2000 requests per ~61 s
Cada 30 s fijos es rápido y desperdicia el 95%: 3,600 llamadas por hora, casi todas vacías. Cada 5 minutos fijos es barato y lento en todo, también en el canal más activo. El backoff por recurso, que duplica el intervalo de un recurso tras cada poll vacío y lo reinicia con el primer evento, se acerca al número de llamadas del plan barato con una mediana de retraso cercana a la del rápido. Es porque los recursos activos se quedan en 30 s y los fríos se van espaciando. El precio es el tope: con 30 minutos, el primer cambio de un recurso frío puede esperar media hora.
Para Codex, esta tabla sobre todo es un argumento para no usar ningún temporizador. Cuando alguien pregunta "¿qué ha cambiado?", una pasada con los cursores guardados cuesta una llamada por recurso vigilado y responde sin ningún retraso para todo lo ocurrido hasta ese momento. El plan con backoff es para un script que mantiene a Codex, o a cualquier otra cosa, vigilando.
¿Qué pasa cuando el propietario retira el acceso?
El propietario quita el proyecto a las 4 h 07 min. Los 30 cursores apuntan ahora a recursos que la conexión no puede leer. La pregunta es cuánto tiempo sigue el cliente consultándolos:
owner removes the project at 4 h 07 min (30 resources lose access):
re-list grants every 10 min failed polls after removal 180, list_granted_resources calls 25
re-list grants every 60 min failed polls after removal 3180, list_granted_resources calls 5
re-list grants on first error failed polls after removal 1, list_granted_resources calls 5
Revisar los permisos con un temporizador o cuesta llamadas o quema miles de polls fallidos. Tratar el primer poll rechazado como un "vuelve a leer los permisos" cuesta un fallo y un list_granted_resources extra. Después, descarta todos los cursores cuyo recurso ya no aparezca en la lista. Si el propietario vuelve a añadir el proyecto más adelante, el cliente empieza esos recursos desde cero.
¿Dónde frenan los schemas a un cliente?
Los casos restantes, comprobados con jsonschema (Draft 2020-12) contra los inputSchema en vivo:
list_project_resources no resource_type REJECT required
list_project_resources limit 50 ok
list_project_resources limit 51 REJECT maximum: limit
list_project_resources graph_session REJECT enum: resource_type
list_project_resources search 101 chars REJECT maxLength: search
poll_resource_events no after_sequence ok
poll_resource_events graph_session ok
poll_resource_events after_sequence -1 REJECT minimum: after_sequence
poll_resource_events limit 100 ok
poll_resource_events limit 101 REJECT maximum: limit
poll_resource_events resource_type project REJECT enum: resource_type
resource_type: "project" es lo primero que prueba casi todo el mundo. Un proyecto no es un recurso con log. Es el permiso que hace visibles los recursos.
El script completo tardó 20.2 s de tiempo real en el M1, 40 llamadas de red incluidas. El tiempo de CPU de usuario fue de 0.91 s.
Si lo montas tú mismo
- Mantén un log por recurso y deja que el cliente guarde el cursor. Así, dos lectores en una misma conexión no se roban eventos y el servidor no guarda estado de lectores.
- Dale a la lista de permisos su propia herramienta sin argumentos y haz que el cliente empiece por ahí. El descubrimiento solo debe devolver lo que el propietario concedió.
- Pon un tope al tamaño de página y explica cómo vaciar (volver a llamar desde la última secuencia hasta recibir una página incompleta).
- Aplica el backoff por recurso, no de forma global. Los recursos activos siguen rápidos y los fríos salen baratos.
- Con el primer poll rechazado, vuelve a leer los permisos y descarta los cursores que ya no existen en lugar de reintentarlos.
- Escribe el cursor después de haber actuado sobre los eventos, para que un fallo los repita en vez de saltárselos.
Cómo decide osFoundry qué herramientas recibe cada conexión está explicado en la página de tool scope. La definición breve del protocolo está en la entrada de MCP del glosario.
Top comments (0)