beta

Conectar un agente con MCP

Tareas compartidas y contexto del producto para tu agente, con tus permisos y un registro de sus acciones.

Dirección del servidor: https://hub.n1.team/mcp · Streamable HTTP · sin sesión de servidor.

Conectar con OAuth

  1. En Claude, ChatGPT u otro cliente MCP remoto con OAuth, añade un servidor propio con la dirección de arriba. La disponibilidad depende del cliente y del plan. Para Cursor, usa la configuración Bearer en la sección Cursor.
  2. Entra en tu cuenta de Hub existente, comprueba el equipo que se muestra y permite el acceso. Cada persona conecta su propio agente. No hace falta copiar una clave.
  3. Envía el mensaje de comprobación de abajo. Una conexión guardada por sí sola no demuestra que el agente haya llegado a Hub.

Para quien implementa el cliente: el descubrimiento usa resource_metadata en el WWW-Authenticate de la respuesta 401, los metadatos del recurso protegido y del servidor de autorización. Authorization Code + PKCE S256, clientes públicos, registro dinámico, scope hub. No se anuncia el grant refresh_token: vuelve a conectar cuando caduque la autorización.

Codex local: conecta OAuth una vez en el perfil compartido de la aplicación, la CLI y el IDE. Reutiliza una conexión existente en lugar de añadir otra.

codex mcp add n1-hub --url https://hub.n1.team/mcp
codex mcp login n1-hub

ChatGPT / Work alojado: instala Hub una vez en Plugins → + → Add custom MCP server, con la dirección de arriba y OAuth. Selecciona el plugin instalado en un chat nuevo si hace falta. Un chat alojado no hereda la config.toml local.

ChatGPT Plugins

Cursor

App de escritorio: Settings → MCPs → New MCP Server abre ~/.cursor/mcp.json. Pon la URL de Hub y Authorization Bearer con una clave personal de Hub. Mejor guarda la clave en N1_HUB_KEY y usa la cabecera de abajo. Los botones Authenticate en Needs Attention son de otros plugins, no de Hub.

{
  "mcpServers": {
    "n1-hub": {
      "url": "https://hub.n1.team/mcp",
      "headers": {
        "Authorization": "Bearer ${env:N1_HUB_KEY}"
      }
    }
  }
}

Los Cloud Agents de Cursor no heredan ~/.cursor/mcp.json ni el .cursor/mcp.json del proyecto. En cursor.com/agents, abre el desplegable MCP y añade Hub con la misma URL y una clave personal de Hub. Los administradores del equipo pueden añadirlo en Dashboard → Plugins & MCPs. Usa HTTP. Los Cloud Agents no admiten SSE ni mcp-remote.

cursor.com/agents · MCP en Cursor · Cloud Agents de Cursor · MCP en la app de Cursor

Conectar con una clave personal

Para clientes sin OAuth, scripts o la configuración local opcional de Codex para tareas y consumo, usa una clave personal en Agentes → Mis conexiones. Reutiliza la clave guardada en los chats de ese perfil. Guárdala como N1_HUB_KEY en el entorno del cliente. La clave se muestra una vez; no la subas al repositorio ni la pongas en una URL. Si se filtra, revócala en tus conexiones. Cada clave pertenece a una persona y a un equipo.

Mis claves

Configuración manual de Codex local: fusiona el bloque con el ~/.codex/config.toml existente, guarda N1_HUB_KEY en ~/.codex/.env y reinicia el cliente. Si CODEX_HOME está definido, usa el directorio de Codex existente. No sustituyas otros ajustes. Esto no conecta un chat alojado.

[mcp_servers.n1-hub]
url = "https://hub.n1.team/mcp"
bearer_token_env_var = "N1_HUB_KEY"

Otros clientes: elige HTTP / Streamable HTTP y configura la cabecera de autorización. Sustituye la clave con el almacén de secretos del cliente; la sintaxis de las variables depende de la aplicación.

Authorization: Bearer <your-personal-key>

Comprobar la conexión

Llama a get_status. Di la persona y el equipo en cuyo nombre actúas. Después list_products y get_product_context de mi producto. No cambies nada todavía.

La respuesta debe nombrar tu persona y tu equipo. Comprueba la primera llamada correcta en Agentes. El agente ve los mismos productos que tú; las operaciones solo del propietario siguen restringidas. Quitar a una persona o revocar una clave detiene las solicitudes siguientes.

En un chat nuevo, con la conexión guardada, repite get_status y lee la tarea prevista con get_task. No hace falta una clave por chat. Si faltan herramientas, comprueba el plugin instalado, el perfil activo del cliente o el entorno en la nube guardado antes de volver a conectar. Una llamada en un chat anterior no demuestra el acceso en este. El acceso OAuth por sí solo no muestra el consumo de tokens.

Implementar un cliente: primera petición del protocolo

Usa un MCP SDK: acuerda una versión de protocolo admitida, llama a initialize, envía notifications/initialized y después tools/list y tools/call. Este curl solo comprueba la inicialización y no ejecuta una herramienta. Pasa la versión acordada en la cabecera MCP-Protocol-Version en las peticiones siguientes. El transporte sin estado no emite Mcp-Session-Id ni ofrece un flujo de eventos persistente por GET.

curl --fail-with-body 'https://hub.n1.team/mcp' \
  -H "Authorization: Bearer $N1_HUB_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

Cómo funciona un cliente MCP · Streamable HTTP

Descubrir las funciones

La referencia completa y actual es la respuesta de tools/list tras autorizar: nombres, descripciones, JSON Schema de los argumentos y anotaciones. Por el mismo cliente están resources/list, resources/templates/list y prompts/list. No fijes el número de herramientas ni des por permitida una operación descubierta para cualquier rol.

EscenarioEmpieza por
Persona y contextoget_status, list_products, get_product_context
Tareas y entregalist_tasks, get_task, create_task, update_task, review_task
Proceso del equipo: columnas y tipos de tarea opcionalesget_workflow, update_workflow · El propietario escribe con expectedVersion y reason; la configuración no arranca un agente.
Cola del agentenext_task, get_agent_work
Datos del productoquery_metric, get_overview, get_sources
Qué ha cambiadoget_digest, daily_digest (indicación)

El contexto del producto también está en n1://products/{slug}/context; plan_week es una indicación de planificación. Lee las instrucciones del servidor y agentPolicy antes de cambiar el trabajo. Cerrar una tarea exige un motivo dicho; tomar el trabajo puede exigir una estimación. Una conexión da acceso, pero no arranca un agente en segundo plano ni ejecuta código. next_task lo llama tu propio agente.

Cómo recogen los agentes las tareas

Depende de la aplicación, no de la marca del modelo: Gemini, GPT y Claude necesitan un cliente en marcha que llame a Hub. Asignar una tarea y conectar MCP no arrancan ese cliente. Hub no envía ahora una señal de despertar a los agentes externos.

Para la recogida automática, configura la aplicación o un planificador externo para que revise la cola y llame a next_task cuando el cliente pueda trabajar. Esa llamada puede tomar una tarea; no es un observador de solo lectura. Usa el identificador de ejecución y la revisión de etapa que devuelve y sigue las reglas del equipo. Sin tarea, la respuesta dice el motivo (code: empty, paused, daily_runs, daily_tokens, needs_estimate, busy) y pollAfterSec indica los segundos para volver a preguntar; REST lo repite en la cabecera Retry-After. busy significa que otra ejecución de la misma clave actuó sobre su tarea hace menos de 90 minutos: termina esta ejecución en lugar de hacer la tarea en paralelo. Para decidir si arrancar un agente, el planificador puede llamar a peek_queue (REST: GET /api/v1/agents/queue): no toma nada y responde pending, queued, holding, code y pollAfterSec. Arranca el modelo solo cuando pending es mayor que 0: una cola vacía no gasta tokens. Si no hay modo en segundo plano ni horario, pide al agente que revise las tareas a mano. Una conexión correcta o una petición reciente no demuestran que el agente escuche la cola sin parar.

Restaurar una conexión existente

Una publicación normal de Hub no exige actualizar cada modelo ni volver a conectar. Si cambia una herramienta conocida, en Agentes aparece un aviso personal para la conexión guardada afectada. Solo lo confirma su propietario. La confirmación oculta el aviso; no demuestra que el cliente se haya actualizado ni que un chat antiguo pueda editar tareas. get_status.mcp describe la revisión del servidor y los avisos personales, no la caché del cliente.

La autorización y las herramientas que recuerda el cliente se actualizan por separado. Tras una publicación de Hub, la conexión puede funcionar mientras la aplicación guarda metadatos viejos de las herramientas. Hub no puede actualizar otra aplicación ni ver un rechazo que ocurre antes de MCP. Una hora de petición anterior no confirma la recuperación.

ChatGPT Plugins · OpenAI: actualizar los metadatos de custom MCP · Ayuda para restaurar la conexión

Comprueba en el mismo cliente solo la lectura: get_status debe nombrar a la persona y al equipo previstos, y después get_task debe leer una tarea real a la que puedan acceder. Pasa la clave real de la tarea, no un ejemplo inventado. Durante la comprobación no cambies nada: next_task puede tomar trabajo y no es una sonda pasiva. Tras actualizar una conexión alojada, haz estas lecturas en la conversación nueva con la autorización anterior.

Antes de dar por bueno el resultado, revisa la respuesta de la herramienta, incluido isError. Tras un tiempo de espera o un resultado de escritura poco claro, vuelve a leer el objeto afectado: la escritura pudo guardarse y la respuesta perderse. Repite la acción solo si la lectura confirma que el cambio no se aplicó. Si el resultado sigue sin estar claro, para y pide ayuda. Si no logras recuperar el trabajo, anota el cliente, el entorno, la herramienta, la hora y el texto del error ya limpio, sin claves, cookies ni códigos OAuth.

Límites y errores

Para scripts HTTP normales, usa la REST API.