Tutorial para fundamentar traducciones MCP de DevSpeak con Context Projects. Explica por qué las herramientas MCP difieren del registro fijo de conectores, cómo crear un proyecto con activos de documento, enlace e imagen, cómo los conectores context7, github y web_search aportan documentación, contexto de repositorio y resultados web, y cómo pasar contextProjectId a translate_text y refine_translation. Documenta el grounding fail-open —un proyecto desconocido o un conector fallido deja la solicitud sin grounding en vez de dar error— y los estados de ingesta pending, processing, ready y failed.

Fundamenta Traducciones MCP en un Context Project

Por defecto toda traducción empieza en frío. Conoce tus parámetros y nada sobre tu código, tus convenciones de nombres o las versiones de librerías que realmente usas.

Los Context Projects resuelven eso. Un proyecto contiene instrucciones, activos ingeridos y un conjunto de conectores — y persiste en cada traducción que ejecutes contra él.

Lo que Aprenderás

Distinguir herramientas MCP de conectores de DevSpeak

Crear un Context Project y agregar activos

Habilitar los conectores context7, github y web_search

Pasar contextProjectId desde herramientas MCP

Razonar sobre el comportamiento fail-open

Requisitos Previos

Una conexión MCP funcionando

Tier VIBECODER o superior — los Context Projects empiezan en VIBECODER, y el servidor MCP se autentica con una clave de API. VIBECODER incluye una clave y 50 solicitudes a la API al mes con el modelo predeterminado; DEVELOPER y superiores no tienen límite mensual de solicitudes

Tiempo Estimado

~11 minutos

Primero, una Distinción que Confunde a Muchos

Son dos capas distintas, y confundirlas causa problemas reales:

| Capa | Ejemplos | Quién la invoca |

| -------------------- | -------------------------------------- | ------------------------------------- |

| Herramientas MCP | translate_text, refine_translation | Tu asistente de IA |

| Conectores | context7, github, web_search | El servidor de DevSpeak, internamente |context7 no es algo que tu asistente invoque. Es uno de los tres conectores del registro fijo de DevSpeak, se habilita por Context Project y se consulta del lado del servidor al construir el prompt. Nunca lo llamas directamente — lo habilitas y luego referencias el proyecto.

El registro está congelado. No existe una vía de registro en tiempo de ejecución, y los tres conectores siguientes son el conjunto completo.

Paso 1 — Crea un Context Project

En el panel de DevSpeak, abre Proyectos en la barra lateral y crea uno.

Dale instrucciones que apliquen a todas las traducciones del proyecto:

``text


Este es un monorepo TypeScript con Express 5 y PostgreSQL.
Todas las respuestas de API usan el envelope { success, data, error }.
Prefiere Zod para validación. Nunca sugieras componentes React de clase.

Estas se aplican a cada traducción fundamentada en este proyecto. Las restricciones que de otro modo reescribirías en customInstructions en cada llamada pertenecen aquí.

`Paso 2 — Agrega Activos`

Se admiten tres tipos de activo:

| Tipo | Origen | Ingesta |


| ------------- | ---------------------------- | ------------------------------------ |
| Documento | Carga de PDF, Markdown o TXT | Texto extraído en el cliente         |
| Enlace    | Una URL pública              | Descargado y extraído en el servidor |
| Imagen    | Carga de PNG, JPEG o WebP    | Almacenada y referenciada            |
Los activos de tipo enlace recorren una máquina de estados observable en la interfaz, donde los estados se muestran como En cola, Procesando, Listo y Falló:

`text


pending → processing → ready
                    ↘ failed

El bloque de código muestra los nombres de estado de la API; la etiqueta en la interfaz de pending es En cola.

Solo se pueden descargar URLs públicas. Un enlace a una dirección privada o insegura se rechaza, y el activo queda en Falló.

Los activos tienen cuota: 25 por proyecto en VIBECODER, 100 en DEVELOPER, ilimitados en ENTERPRISE.

`Punto de Control`

En este punto deberías tener:

[ ] Un Context Project con instrucciones guardadas


[ ] Al menos un activo en estado Listo
[ ] El ID del proyecto tomado de la URL o del encabezado del proyecto
Paso 3 — Habilita Conectores
Abre el panel de conectores y habilita los que el proyecto necesite. Cada conector también requiere configuración antes de poder recuperar algo:

context7 — obtiene documentación actual de librerías. Es valioso porque los datos de entrenamiento van por detrás de los lanzamientos reales; así una traducción usa la API que efectivamente ejecutas y no la de hace dos versiones mayores. Requiere tu propia clave de API de Context7 y al menos un ID de biblioteca de Context7.

github — aporta contexto del repositorio para que el código generado siga la estructura y los nombres existentes. Requiere tu propio token de acceso personal de GitHub (de alcance detallado, solo lectura de Contents y Metadata) y un repositorio con el formato owner/repo.

web_search — recupera documentación técnica en tiempo real para lo que quede fuera de los otros dos. Requiere tu propia clave de API de Tavily.

Conecta cada credencial desde el panel de conectores. Las credenciales son tuyas, se almacenan cifradas y se usan solo en tus peticiones — DevSpeak no sustituye un token compartido. Un conector sin su credencial, repositorio o ID de biblioteca no aporta nada y, como el grounding falla en abierto, la traducción igual se completa sin él.

Habilita solo lo necesario. Cada conector agrega un paso de recuperación antes de que empiece la generación, así que uno innecesario vuelve más lenta cada petición de ese proyecto y hace más probable que expire.

`Paso 4 — Fundamenta una Traducción`

Pasa el ID del proyecto como contextProjectId:

> Usa translate_text con contextProjectId "proj_a1b2c3", audience "Senior Dev", context "Backend", format "Technical Spec" y tone 70.

`json

{


  "input": "Agregar rate limiting a los endpoints de notas.",
  "audience": "Senior Dev",
  "context": "Backend",
  "format": "Technical Spec",
  "tone": 70,
  "contextProjectId": "proj_a1b2c3"
}

La salida ahora referencia la forma real de tu envelope, usa Zod y apunta a Express 5 — porque las instrucciones así lo indicaron.

refine_translation acepta el mismo parámetro. Pásalo en ambas llamadas, o un refinamiento perderá el grounding que tenía la traducción original.

`El Grounding Falla en Abierto — Entiende Esto`

Es el comportamiento más importante de la funcionalidad:

> Si contextProjectId no existe, tu tier no incluye Context Projects, o un conector falla, la petición igual tiene éxito — sin fundamentar.

No hay error. Recibes una traducción normal que simplemente ignoró tu proyecto.

Es una decisión deliberada de disponibilidad: un conector caído no debe romper la traducción. Pero implica que un ID mal escrito parece un éxito mientras produce salida genérica en silencio.

Cómo saber si el grounding realmente aplicó: busca en la salida algo que solo tu proyecto conoce. Si tus instrucciones especifican el envelope { success, data, error } y la salida inventa otra forma, el grounding no aplicó. Verifica el ID y confirma que tu tier incluya la funcionalidad.

`Combinar Grounding con Búsqueda Web`

contextProjectId y la bandera webSearch son independientes y se combinan:

`json


{
  "input": "Migrar nuestro rate limiter a la nueva API de middleware.",
  "audience": "Senior Dev",
  "context": "Backend",
  "format": "Technical Spec",
  "tone": 70,
  "contextProjectId": "proj_a1b2c3",
  "webSearch": true
}

El proyecto aporta tus convenciones; webSearch aporta la documentación upstream actual. Juntos producen un plan de migración fundamentado en ambas.

`Solución de Problemas`

La salida ignora las instrucciones de mi proyecto

El grounding falló en abierto. Verifica el ID exacto del proyecto, confirma tu tier con get_account_info y revisa que los activos estén en Listo y no en Falló, y que cada conector habilitado tenga su credencial y su repositorio o ID de biblioteca.

Un activo quedó en Falló

Abre el activo para ver el motivo en línea. Las causas habituales son un timeout de descarga, una URL rechazada por privada o insegura, o un archivo mayor al límite de 10 MB.

Las peticiones fundamentadas expiran

Cada conector suma tiempo de recuperación, así que un proyecto con varios conectores habilitados tiene más probabilidad de expirar. Deshabilita los conectores que el proyecto no necesite, empezando por web_search.

HTTP 403 al crear un proyecto

Los Context Projects requieren VIBECODER o superior. Un 403 en una llamada de traducción hecha con una clave de API es otra restricción: en GRATIS o VIBECODER se agotaron las 50 solicitudes mensuales a la API o se fijó un modelo; error indica cuál. DEVELOPER y superiores no tienen ese límite.

Ediciones rápidas devuelven HTTP 429

Los cambios de proyecto tienen límite de tasa, así que una ráfaga de ediciones puede devolver 429. La respuesta incluye Retry-After como encabezado y como campo retryAfter. El panel agrupa las ediciones en una sola petición; los clientes programáticos deben respetar ese valor.

`Resumen`

Aprendiste a:

Separar las herramientas MCP del registro fijo de conectores de DevSpeak


Crear un Context Project con instrucciones y activos

Habilitar context7, github y web_search

Fundamentar traducciones MCP con contextProjectId`

Detectar el grounding fail-open en lugar de confiar en él a ciegas

Siguientes Pasos

[Maneja Errores, Límites de Tasa y Selección de Modelo en MCP](/tutorials/mcp/handle-errors-and-model-selection)

[Conecta el Servidor MCP de DevSpeak](/tutorials/mcp/connect-the-mcp-server)