> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tess.im/llms.txt
> Use this file to discover all available pages before exploring further.
# Servidor MCP
> Conecta Tess AI con Claude, Cursor, Codex y cualquier plataforma compatible con MCP — de forma segura, usando tu propio token de API.
El **Servidor MCP de Tess AI** convierte tus agentes, ejecuciones y memorias de Tess en herramientas que cualquier cliente del **Model Context Protocol (MCP)** puede invocar. Es un **endpoint alojado y gestionado**: no hay nada que instalar, empaquetar ni ejecutar.
Apunta tu plataforma de IA a una única URL, autentícate con tu **token de API de Tess** y tu equipo podrá listar, ejecutar y orquestar agentes de Tess directamente desde las herramientas que ya usa.
**Endpoint:** `https://mcp.tess.im` — un servidor MCP remoto que usa el transporte **Streamable HTTP**. Sin `npx`, sin proceso local, sin necesidad de Node.js.
## Por qué conectar mediante MCP
Ejecuta agentes de Tess dentro de Claude, Cursor, Codex o tus propias herramientas internas — sin cambiar de contexto, sin copiar y pegar.
Un endpoint gestionado por Tess. Las nuevas capacidades aparecen automáticamente; no hay cliente que actualizar.
Cada llamada se ejecuta con el token y el workspace de quien la realiza, heredando tus roles, permisos y límites de créditos existentes.
Construido sobre el protocolo abierto MCP. El mismo endpoint funciona en todas las plataformas compatibles — sin integración por proveedor.
## Qué expone el servidor
El conjunto de herramientas se **genera automáticamente a partir de la API de Tess** — cada endpoint se convierte en una herramienta MCP, así que las nuevas capacidades de la API aparecen sin ningún cambio en el servidor. Todas las herramientas están listadas abajo, agrupadas por dominio, cada una con su propia entrada enlazable en [Referencia de herramientas](#tools-reference).
| Dominio | Herramientas |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agentes** | [`list_agents`](#list-agents) · [`get_agent`](#get-agent) · [`execute_agent`](#execute-agent) · [`list_files_agent`](#list-files-agent) · [`link_files_agent`](#link-files-agent) · [`delete_file_link_agent`](#delete-file-link-agent) · [`list_agent_responses`](#list-agent-responses) · [`get_agent_response`](#get-agent-response) · [`list_agent_webhooks`](#list-agent-webhooks) · [`create_agent_webhook`](#create-agent-webhook) · [`agent_chat_completions`](#agent-chat-completions) |
| **Archivos** | [`list_files`](#list-files) · [`upload_file`](#upload-file) · [`get_file`](#get-file) · [`delete_file`](#delete-file) · [`process_file`](#process-file) · [`resolve_durable_file_reference`](#resolve-durable-file-reference) |
| **Memorias** | [`list_memories`](#list-memories) · [`create_memory`](#create-memory) · [`update_memory`](#update-memory) · [`delete_memory`](#delete-memory) · [`import_memories_text`](#import-memories-text) · [`get_memory_import_status_result`](#get-memory-import-status-result) |
| **Webhooks** | [`list_webhooks`](#list-webhooks) · [`delete_webhook`](#delete-webhook) |
| **Créditos y workspace** | [`deduct_credits_user`](#deduct-credits-user) · [`get_workspace_usage`](#get-workspace-usage) |
Esta lista cubre todas las herramientas relevantes para una integración de terceros. También existen herramientas de organización de carpetas/chats (usadas internamente por la interfaz web de Tess), pero no se documentan aquí — pídele a tu asistente que "liste las herramientas disponibles" para ver el conjunto completo y actual directamente desde tu cliente MCP.
## Antes de empezar
Necesitas dos datos de la plataforma Tess:
Genera un token de acceso personal en **[Tess AI → Tokens de API](https://tess.im/dashboard/user/tokens)**. Es el mismo token usado en toda la API de Tess — consulta el [Quickstart](https://docs.tess.im/api/get-started/quickstart) para más detalles.
El servidor MCP está **delimitado por workspace**. Encuentra el ID de tu workspace en la URL del panel de Tess o en la configuración del workspace, y usa el del workspace cuyos agentes quieres alcanzar. Cada llamada queda aislada a ese workspace.
Trata tu token de API como una contraseña. Otorga acceso a los agentes y ejecuciones de tu workspace, que pueden consumir créditos. Prefiere un token dedicado por integración para poder revocarlo de forma independiente.
## Autenticación
Las credenciales se envían **solo como encabezados HTTP** — nunca como parámetros de URL, para que los tokens no terminen en logs ni en el historial del navegador:
```
Authorization: Bearer TU_TOKEN_DE_API
x-workspace-id: TU_WORKSPACE_ID
```
Ambos encabezados son obligatorios en cada solicitud. **Obligatorio a partir del 01/09/2026** para el alcance de workspace de la API Tess (misma política del header de la API REST). No hay alternativa mediante parámetros de URL — tu cliente MCP debe admitir el envío de encabezados personalizados.
## Conecta tu plataforma
```bash theme={null}
claude mcp add tess --transport http https://mcp.tess.im \
--header "Authorization: Bearer TU_TOKEN_DE_API" \
--header "x-workspace-id: TU_WORKSPACE_ID"
```
Luego, en una sesión: *"Usa Tess para ejecutar el agente de Code Review en este diff."*
Agrega Tess a tu configuración MCP (en Cursor: **Tools & Integrations → MCP Tools**, o `~/.cursor/mcp.json`):
```json theme={null}
{
"mcpServers": {
"tess": {
"url": "https://mcp.tess.im",
"headers": {
"Authorization": "Bearer TU_TOKEN_DE_API",
"x-workspace-id": "TU_WORKSPACE_ID"
}
}
}
}
```
Agrega un servidor MCP remoto con encabezados en `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.tess]
url = "https://mcp.tess.im"
headers = { Authorization = "Bearer TU_TOKEN_DE_API", "x-workspace-id" = "TU_WORKSPACE_ID" }
```
La sintaxis de configuración puede cambiar entre versiones de Codex CLI — consulta `codex mcp --help` o la documentación actual de Codex si esto no coincide con lo que ves.
Estas plataformas se conectan a servidores MCP remotos mediante una interfaz de "conector personalizado". Para funcionar con Tess, la configuración del conector debe permitir definir **dos** cosas:
* La URL del endpoint: `https://mcp.tess.im`
* **Dos** encabezados personalizados: `Authorization: Bearer TU_TOKEN_DE_API` y `x-workspace-id: TU_WORKSPACE_ID`
Algunas interfaces de conector solo exponen un único campo de bearer token y no admiten agregar un segundo encabezado personalizado — consulta la documentación actual de tu plataforma para saber si admite encabezados personalizados (además de un bearer token) para conectores MCP remotos. Si tu plataforma solo admite un encabezado de autenticación, usa uno de los clientes con soporte de encabezados anteriores (Claude Code, Cursor, Codex CLI) o una integración personalizada.
## Cómo funciona la autenticación
El servidor MCP es una **puerta de enlace sin estado**. No almacena tus credenciales. En cada solicitud:
1. Lee tu token de API y el ID del workspace desde los encabezados de la solicitud.
2. Reenvía la llamada a la API de Tess **como tú**, exactamente como lo haría una llamada directa a la API.
3. Devuelve el resultado a tu cliente MCP.
Esto significa que el servidor hereda **todos** los controles existentes de tu plataforma:
Las llamadas se ejecutan con la identidad del propietario del token. La visibilidad de agentes, los roles y los permisos de funciones los aplica Tess, sin atajos.
Cada solicitud se vincula al `x-workspace-id` enviado. Un token no puede alcanzar datos de otro workspace.
Las ejecuciones consumen créditos según los límites y la facturación de tu workspace — igual que la API de Tess.
Revoca un token en el panel para cortar al instante cualquier plataforma conectada que lo use. Sin necesidad de redeploy.
## Referencia de herramientas
list\_agents
Lista los agentes disponibles en el workspace, con búsqueda y paginación.
Busca agentes por título, descripción y descripción larga.
Filtra por tipo de agente.
Número de página para la paginación.
Cantidad de agentes por página.
get\_agent
Devuelve los detalles completos de un agente (entradas, tipo, descripción).
El ID del agente.
execute\_agent
Ejecuta un agente con las entradas indicadas y, opcionalmente, espera el resultado.
El ID del agente.
Las respuestas del agente. Para agentes de tipo chat, incluye un array `messages` (pares `role`/`content`, con el mismo formato que OpenAI Chat Completions).
Cuando es `true`, espera a que termine la ejecución y devuelve la salida final. Cuando es `false`, devuelve de inmediato para que consultes la ejecución después.
list\_files\_agent
Obtiene la lista de archivos asociados a un agente específico.
ID del agente para el cual recuperar los archivos.
link\_files\_agent
Asocia uno o más archivos a un agente específico.
ID del agente al que vincular los archivos.
Array de IDs de archivos a vincular al agente.
delete\_file\_link\_agent
Elimina la asociación entre un archivo específico y un agente.
ID del agente del que eliminar el vínculo del archivo.
ID del archivo a desvincular del agente.
list\_agent\_responses
Lista respuestas de ejecuciones de agentes, con filtros y paginación.
Busca agentes por título.
Filtra por el ID de ejecución raíz.
Filtra por el ID del agente.
Filtra por tipo de agente.
Ordena de forma ascendente o descendente (`asc`/`desc`).
Página actual.
Cantidad de elementos por página.
get\_agent\_response
Obtiene una respuesta de ejecución de agente específica por ID.
El ID de la ejecución del agente.
list\_agent\_webhooks
Lista los webhooks registrados para un agente específico.
ID del agente.
Página actual.
Cantidad de elementos por página.
create\_agent\_webhook
Registra un nuevo webhook en un agente específico.
El ID del agente.
La URL de destino del webhook.
Método HTTP usado en la llamada del webhook.
Estado del webhook (`active`/inactivo).
agent\_chat\_completions
Ejecuta un agente a través de una interfaz compatible con OpenAI Chat Completions — útil para clientes ya integrados con el formato de la API de OpenAI.
El ID del agente.
Un cuerpo de solicitud con el formato de OpenAI Chat Completions.
list\_files
Obtiene una lista paginada de archivos del workspace, con opciones de ordenación.
Número de página para la paginación.
Cantidad de elementos por página (máx. 100).
Orden de clasificación por el campo `created_at` (`asc`/`desc`).
upload\_file
Sube un nuevo archivo al workspace y opcionalmente lo procesa.
El archivo a subir.
Si el archivo debe procesarse inmediatamente después de subirlo.
get\_file
Devuelve los detalles de un archivo específico.
El ID del archivo.
delete\_file
Elimina un archivo del workspace.
El ID del archivo.
process\_file
Activa (o reactiva) el procesamiento de un archivo ya subido.
El ID del archivo.
resolve\_durable\_file\_reference
Resuelve una referencia de artefacto durable `doc://` (devuelta como `ref_url`) en una URL de descarga firmada, recién generada y de corta duración. La identidad y el alcance del workspace provienen de tu token de API.
La referencia de artefacto durable a resolver.
list\_memories
Lista las memorias almacenadas en el workspace.
Filtra por colección de memorias.
Número de página para la paginación.
Elementos por página (máx. 50).
create\_memory
Guarda una nueva memoria en una colección.
La colección de memorias donde almacenarla.
El texto de la memoria a almacenar (máx. 32.000 caracteres).
update\_memory
Edita una memoria existente.
La memoria a actualizar.
Nuevo texto de la memoria.
Mueve la memoria a otra colección.
delete\_memory
Elimina una memoria existente.
La memoria a eliminar.
import\_memories\_text
Activa una importación masiva de memorias desde texto libre. Asíncrono por defecto.
Si debe bloquear hasta que la importación se complete (con tiempo límite acotado) en lugar de devolver de inmediato.
get\_memory\_import\_status\_result
Devuelve el estado y el resumen de una ejecución de importación de memorias.
El ID de la ejecución de importación.
list\_webhooks
Lista todos los webhooks del workspace.
Página actual.
Cantidad de elementos por página.
delete\_webhook
Elimina un webhook por ID.
El ID del webhook.
deduct\_credits\_user
Deduce créditos de un usuario específico según el factor base del sistema de créditos y los parámetros de cálculo. Pensado para integraciones a nivel de plataforma que miden el uso de un recurso personalizado.
Identificador del usuario/workspace del que se deducirán los créditos.
Tipo de recurso que se está midiendo (por ejemplo, `image`).
Valor numérico positivo usado en el cálculo de créditos.
El ID del workspace.
ID del recurso que se está midiendo.
Entradas adicionales para el cálculo de créditos.
get\_workspace\_usage
Devuelve el uso del workspace desglosado por tipo y rango de fechas.
Filtro de rango de fechas predefinido (`1d`/`7d`/`30d`).
Fecha de inicio personalizada (`YYYY-MM-DD`). Úsala con `end_date`; sobrescribe `range`.
Fecha de fin personalizada (`YYYY-MM-DD`). Úsala con `start_date`; sobrescribe `range`.
Filtra por ID de usuario (requiere el permiso `WORKSPACE_DOCUMENTS_READ`).
Filtra por tipo de uso (`chat`, `image`, `text`, `tool_execution`, `connector_calls`, entre otros).
Número de página para la paginación.
## Ejemplo: ejecuta un agente de principio a fin
Una vez conectado, puedes conducir un flujo completo en lenguaje natural:
*"Lista mis agentes de Tess"* → el asistente invoca [`list_agents`](#list-agents) y muestra lo disponible.
*"Guarda en mi colección 'Estándares de Ingeniería': escribe siempre pruebas unitarias con BDD"* → [`create_memory`](#create-memory).
*"Usa el agente de Code Review para revisar esta función, y espera el resultado"* → [`execute_agent`](#execute-agent) devuelve la salida al instante.
*"Lista mis memorias"* → [`list_memories`](#list-memories) confirma lo almacenado para futuras ejecuciones.
## Gobernanza y cumplimiento
* **Privilegio mínimo** — conéctate con un token delimitado a un único workspace y solo con los permisos que esa integración necesita.
* **Auditabilidad** — las ejecuciones disparadas vía MCP aparecen en el historial y el uso de tu workspace en Tess, como cualquier llamada a la API.
* **Sin almacenamiento de credenciales** — la puerta de enlace no tiene estado; los tokens viven solo en la configuración de tu cliente MCP.
* **Revocación centralizada** — desactivar un token en el panel bloquea de inmediato todas las plataformas que lo usan.
## Solución de problemas
Confirma que tu cliente usa el transporte **Streamable HTTP** (remoto) en lugar de un comando local/stdio, y que apunta directamente a `https://mcp.tess.im` (sin ruta adicional).
Ambos encabezados son obligatorios en cada solicitud — `Authorization: Bearer TU_TOKEN_DE_API` y `x-workspace-id: TU_WORKSPACE_ID`. No hay opción mediante parámetros de URL; confirma que tu cliente admite el envío de encabezados personalizados y que el token está activo en el panel.
Falta el ID del workspace, está mal formado, o el token no tiene acceso a él. Confirma que el encabezado `x-workspace-id` esté definido y corresponda a un workspace accesible por tu token.
Algunos agentes requieren entradas específicas. Los agentes de tipo chat, por ejemplo, esperan un array `messages` dentro de `body`. Pide al asistente que inspeccione los campos del agente ([`get_agent`](#get-agent)), o revisa el agente en la plataforma Tess.
## Recursos
* [Model Context Protocol — sitio oficial](https://modelcontextprotocol.io)
* [Cómo crear un Token de API en Tess AI](https://docs.tess.im/api/get-started/quickstart)