MeatSpace

Humano en el bucle para agentes de IA. Envía contenido + 2–4 opciones, recibe una decisión humana estructurada.

Documentación

MeatSpace

Servicio de intervención humana para agentes de IA. Cuando un agente se enfrenta a una decisión subjetiva, de alto riesgo o ambigua, MeatSpace la enruta a un humano que elige una de 2 a 4 opciones y devuelve un resultado estructurado.

Disponible en meatspace.run

Qué hace

Un agente publica un título, contenido opcional (texto, markdown, HTML o una imagen) y de 2 a 4 opciones etiquetadas. A un revisor humano se le muestra la solicitud, elige una, y la API devuelve el id y label seleccionados. El agente espera mediante long-poll o webhook.

Casos de uso típicos:

Puertas de aprobación antes de acciones destructivas o irreversibles (despliegues, eliminaciones, pagos).
Desempates subjetivos cuando el modelo está por debajo de su umbral de confianza.
Decisiones de criterio — opciones de redacción, preferencias de diseño, empates en clasificaciones.
Escalamiento cuando un agente ha agotado sus comprobaciones deterministas.

No lo uses cuando la tarea sea determinista, verificable automáticamente, o de bajo riesgo y fácilmente reversible.

Tres métodos de integración

Método	Endpoint	Mejor para
API REST	`POST /api/requests`	Cualquier cliente HTTP, frameworks de agentes personalizados, servidor a servidor.
MCP	`POST /api/mcp` (HTTP Streamable)	Claude, Claude Code, clientes compatibles con MCP.
SDK de navegador	`/sdk/meatspace.js`	Agentes que se ejecutan en una pestaña del navegador.

Los tres se basan en la misma API subyacente y aceptan el mismo token Bearer.

Flujo de autoservicio sin configuración

Un agente nuevo puede incorporarse completamente en tres llamadas — sin página de registro, sin cola de aprobación, sin humanos en el bucle de configuración:

POST /api/keys con {"name": "your-agent", "email": "owner@example.com"} → devuelve una clave API al instante. Limitada a 5 claves por correo electrónico.
POST /api/requests con el token Bearer, tu título y opciones → crea la solicitud de revisión.
GET /api/requests/{id}/wait → se bloquea hasta que el humano responde, o agota el tiempo y devuelve pending con un review_url y poll_url.

El mismo flujo está disponible a través de MCP: initialize → tools/list → provision_api_key → ask_human. Las herramientas provision_api_key y get_service_status no requieren autenticación, por lo que un cliente MCP nuevo puede conectarse sin credenciales e incorporarse por sí mismo.

Inicio rápido con REST

Aprovisiona una clave:

curl -X POST https://meatspace.run/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "email": "you@example.com"}'

La respuesta incluye api_key — se muestra una vez, guárdala. Todas las llamadas posteriores usan Authorization: Bearer <token>.

Crea una solicitud:

curl -X POST https://meatspace.run/api/requests \
  -H "Authorization: Bearer $MEATSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "my-agent",
    "title": "Ship v2.0 to production?",
    "content": "All tests pass. Staging looks good. 2 minor lint warnings.",
    "choices": [
      { "id": "ship", "label": "Ship it" },
      { "id": "wait", "label": "Wait for next cycle" }
    ],
    "confidence": 0.7,
    "consequence_of_wrong_choice": "Premature ship affects ~50k users"
  }'

Respuesta:

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "pending",
    "review_url": "https://meatspace.run/review/uuid?token=opaque-review-token",
    "poll_url": "/api/requests/uuid",
    "expires_at": "2026-04-23T19:00:00.000Z"
  }
}

Long-poll para el resultado:

curl https://meatspace.run/api/requests/{id}/wait?timeout=25000 \
  -H "Authorization: Bearer $MEATSPACE_API_KEY"

Devuelve { status: "completed", selected, selected_label, responded_at } cuando el humano responde, o 202 si aún está pendiente.

Campos opcionales en POST /api/requests: content_type (text por defecto, markdown, html, image), decision_reason, confidence (0–1), consequence_of_wrong_choice, recommended_option, callback_url (debe ser HTTPS y estar en la lista blanca del host), metadata (se pasa al webhook), run_id, trace_id, timeout_seconds (3600 por defecto, máximo 86400).

MCP

MeatSpace implementa MCP sobre HTTP Streamable en https://meatspace.run/api/mcp. El servidor expone tres herramientas:

get_service_status — disponibilidad y orientación de escalamiento. Sin autenticación.
provision_api_key — emite un token Bearer. Sin autenticación, con límite de velocidad.
ask_human — envía una decisión. Requiere autenticación Bearer.

Configuración de Claude Code:

{
  "mcpServers": {
    "meatspace": {
      "type": "url",
      "url": "https://meatspace.run/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

ask_human hace long-poll durante hasta 20 segundos. Si el humano no ha respondido para entonces, la herramienta devuelve status: "pending" con un review_url (para el humano) y un poll_url (para el agente).

SDK de navegador

Para agentes que se ejecutan en contextos de navegador:

<script type="module">
  import { MeatSpace } from 'https://meatspace.run/sdk/meatspace.js';

  const ms = new MeatSpace();
  await ms.getKey({ name: 'browser-agent', email: 'agent@example.com' });

  const result = await ms.ask({
    agentName: 'browser-agent',
    title: 'Which option?',
    choices: [
      { id: 'a', label: 'A' },
      { id: 'b', label: 'B' },
    ],
  });
  console.log(result.selected);
</script>

Métodos: getKey(), createRequest(), pollResult(), waitForResult(), ask() (crear + esperar).

Webhooks

Si callback_url está configurado en la solicitud, MeatSpace envía el resultado por POST cuando el humano responde:

{
  "event": "request.completed",
  "request_id": "uuid",
  "selected": "ship",
  "selected_label": "Ship it",
  "responded_at": "2026-04-23T18:10:00.000Z",
  "metadata": {}
}

callback_url debe ser https:// y el nombre de host debe estar explícitamente en la lista blanca del operador. Si no hay lista blanca configurada, la creación de solicitudes rechaza las URL de callback. Cada entrega está firmada con los encabezados X-HITL-Timestamp y X-HITL-Signature.

Endpoints de descubrimiento

Ruta	Formato	Propósito
`/.well-known/mcp.json`	JSON	Manifiesto del servidor MCP
`/.well-known/agent.json`	JSON	Tarjeta de agente A2A
`/api/openapi`	JSON	Especificación OpenAPI 3.1
`/api/mcp` (GET)	JSON	Información del servidor MCP, sin autenticación
`/api/status`	JSON	Verificación de salud + orientación para agentes
`/sdk/meatspace.js`	JavaScript	SDK de navegador
`/llms.txt`	Texto	Resumen legible por LLM
`/llms-full.txt`	Texto	Documentación completa de la API
`/agents.md`	Markdown	Guía de integración completa
`/sitemap.xml`	XML	Mapa del sitio
`/robots.txt`	Texto	Directivas de rastreadores + punteros de descubrimiento

Errores

Todos los errores devuelven:

{
  "success": false,
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

Códigos comunes: agent_name_required, invalid_choice_count, content_too_large, callback_url_not_allowed, request_create_failed.

Desarrollo local

Este repositorio es una aplicación Next.js 14 desplegada en Cloudflare Pages.

npm install
npm run dev          # local dev at http://localhost:3000
npm run test         # integration tests
npm run build:cf     # build for Cloudflare Pages
npm run deploy:cf    # build and deploy

Supabase es el sistema de registro para claves y solicitudes; Resend gestiona el correo electrónico transaccional.

Licencia

MIT