Contentu

API y MCP para agentes

Tu agente puede leer Contentu igual que lo lees tú: el directorio de herramientas, los empleos remotos, el blog, los eventos, los retos y las fichas de los cursos. Con una llave de tu cuenta también lee tu perfil, tus puntos, tu avance y, si tienes Contentu Lab+, el contenido de miembros. Hoy todo es de solo lectura.

Sin costo. Lo público no necesita llave.

Conectar por MCP

El servidor MCP de Contentu usa Streamable HTTP sin sesiones en esta dirección:

https://www.contentu.co/api/agents/mcp

En Claude Code, sin llave (solo lo público):

claude mcp add --transport http contentu https://www.contentu.co/api/agents/mcp

Con una llave de tu cuenta (lo público más lo que permita la llave):

claude mcp add --transport http contentu https://www.contentu.co/api/agents/mcp \
  --header "Authorization: Bearer ctu_live_xxxxxxxx_…"

En otros clientes, usa la misma dirección y, si quieres lo de tu cuenta, agrega la cabecera Authorization: Bearer con tu llave.

Cada operación de la tabla de abajo es una herramienta MCP con el mismo nombre. La lista de herramientas cambia según la llave: sin llave ves solo las públicas.

Para conectar tu cuenta desde Claude.ai, ChatGPT u otro cliente que use OAuth, agrega un conector personalizado con esta dirección. Te pedirá entrar a Contentu y elegir qué permisos darle; lo desconectas cuando quieras en Mi cuenta → API.

https://www.contentu.co/api/agents/mcp/cuenta

Usar la API REST

Todas las rutas cuelgan de esta base y responden JSON:

https://www.contentu.co/api/agents/v1

Todas aceptan lang=es o lang=en. Las listas aceptan limit (hasta 50) y devuelven next_cursor: pásalo como cursor para la página siguiente.

Ejemplo con datos de prueba (respuesta recortada):

curl "https://www.contentu.co/api/agents/v1/tools?limit=1&lang=es"
{
  "data": [
    {
      "slug": "ejemplo-automatiza",
      "name": "Ejemplo Automatiza",
      "description": "Herramienta de ejemplo para automatizar flujos sin código.",
      "categories": [
        "automatizacion"
      ],
      "recommended_by_contentu": true,
      "sponsored": false,
      "affiliate_link": true,
      "disclosure": "Enlace de afiliado: si compras, Contentu recibe una comisión sin costo extra para ti",
      "visit_url": "https://automatiza.example/?ref=contentu",
      "url": "https://www.contentu.co/es/herramientas/ejemplo-automatiza"
    }
  ],
  "next_cursor": "eyJzIjoibGlz…"
}

Con llave:

curl -H "Authorization: Bearer ctu_live_xxxxxxxx_…" "https://www.contentu.co/api/agents/v1/me/points"
{
  "points": 180,
  "points_this_month": 60,
  "level": 3,
  "level_name": "Creador",
  "next_level": {
    "name": "Colaborador",
    "points_missing": 120
  },
  "percent_to_next_level": 20
}

Operaciones

Herramienta MCPRuta RESTAcceso
list_toolsBuscar herramientasGET /toolsPública
get_toolVer una herramientaGET /tools/{slug}Pública
list_jobsBuscar empleos remotosGET /jobsPública
get_jobVer un empleoGET /jobs/{id}Pública
list_postsListar artículos del blogGET /postsPública; los de miembros con content:read
get_postLeer un artículo del blogGET /posts/{slug}Pública; los de miembros con content:read
list_eventsListar eventosGET /eventsPública
get_eventVer un eventoGET /events/{slug}Pública
list_challengesListar retosGET /challengesPública
get_challengeVer un retoGET /challenges/{slug}Pública
list_coursesListar cursosGET /coursesPública
get_courseVer un cursoGET /courses/{slug}Pública
get_limitsVer límites de usoGET /limitsPública
get_meVer mi perfil y mi planGET /meLlave con profile:read
get_my_pointsVer mis puntos y mi nivelGET /me/pointsLlave con points:read
get_my_learningVer mis cursos, retos y progresoGET /me/learningLlave con learning:read
get_course_sessionLeer una sesión de un cursoGET /courses/{slug}/sessions/{n}Llave con content:read
list_saved_jobsVer mis vacantes guardadasGET /me/saved-jobsLlave con jobs:save
save_jobGuardar una vacantePOST /me/saved-jobsLlave con jobs:save
unsave_jobQuitar una vacante guardadaDELETE /me/saved-jobs/{job_id}Llave con jobs:save
set_saved_job_statusAnotar cómo va una vacante guardadaPOST /me/saved-jobs/{id}/statusLlave con jobs:save

Llaves y permisos

Las llaves se crean en Mi cuenta. Cada llave tiene un nombre, los permisos que elijas y una fecha de vencimiento (30, 90 o 180 días). Puedes tener hasta 5 activas y revocarlas cuando quieras.

  • profile:read: Tu perfil y tu plan
  • learning:read: Tus cursos, retos y avance
  • points:read: Tus puntos y tu nivel
  • content:read: Contenido de miembros (solo si tienes Contentu Lab+)
  • jobs:save: Guardar vacantes y anotar cómo va cada una (solo si tienes Contentu Lab+)

Una llave se ve así: ctu_live_ seguido de un identificador y un secreto. Se muestra una sola vez; Contentu guarda solo una huella cifrada.

El plan no queda guardado en la llave: en cada petición se revisa el de tu cuenta. Si tu membresía termina, la llave deja de abrir el contenido de miembros.

Crear o revocar llaves

Límites

  • Sin llave: 30 peticiones por minuto por dirección IP.
  • Con llave: 120 peticiones por minuto por llave.
  • Con llave, cada dirección IP puede fallar la revisión de la llave hasta 30 veces por minuto (llave equivocada, vencida o revocada). Después recibe 429. Las peticiones con una llave válida no cuentan aquí.
  • Listas de hasta 50 elementos por página. Los textos largos llegan recortados con truncated: true y el enlace a la página completa.
  • Si pasas el límite recibes 429 con la cabecera Retry-After en segundos.

Errores

En la API REST los errores llegan como application/problem+json con un code que no cambia y un request_id para soporte.

En MCP llegan como resultado con isError, el mismo code y el request_id.

CódigoEstadoQué significa
invalid_request400La petición no es válida
invalid_cursor400El cursor no es válido o ya no sirve
unauthorized401Falta una llave válida
key_revoked401Esta llave fue revocada
key_expired401Esta llave venció
key_blocked403El acceso de esta llave está bloqueado
insufficient_scope403A esta llave le falta un permiso
membership_required403Este contenido es para miembros de Contentu Lab+
admin_required403Esta llave no puede administrar Contentu ahora
origin_not_allowed403Este origen no puede llamar a la puerta
not_found404No existe
method_not_allowed405Método no permitido
invalid_state409El recurso no está en un estado que lo permita
conflict409Ya existe un recurso con ese identificador
payload_too_large413El cuerpo supera el tamaño permitido
unsupported_media_type415El cuerpo debe ser JSON
rate_limited429Demasiadas peticiones; espera un momento
internal_error500Algo falló de nuestro lado
not_available501Esta operación todavía no está disponible
not_configured503La puerta no está configurada
temporarily_unavailable503No disponible por un momento; reintenta

Reglas de uso

  • Si muestras un enlace de una herramienta con affiliate_link en true, muestra también el texto de disclosure junto a él.
  • Postular a un empleo es gratis y se hace en el sitio del empleador o de la fuente. Menciona la fuente de cada vacante.
  • El contenido de miembros es para la persona dueña de la llave: no lo publiques ni lo compartas.
  • No uses la API para enviar spam, hacer scraping masivo ni saltarte los límites.

Términos de uso de la API y el MCP

Para máquinas