> ## 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
> Conecte a Tess AI ao Claude, Cursor, Codex e qualquer plataforma compatível com MCP — com segurança, usando o seu próprio token de API.
O **Servidor MCP da Tess AI** transforma seus agentes, execuções e memórias da Tess em ferramentas que qualquer cliente do **Model Context Protocol (MCP)** pode chamar. É um **endpoint hospedado e gerenciado**: não há nada para instalar, empacotar ou executar.
Aponte sua plataforma de IA para uma única URL, autentique-se com o seu **token de API da Tess** e sua equipe poderá listar, executar e orquestrar agentes da Tess diretamente nas ferramentas que já utiliza.
**Endpoint:** `https://mcp.tess.im` — um servidor MCP remoto que usa o transporte **Streamable HTTP**. Sem `npx`, sem processo local, sem necessidade de Node.js.
## Por que conectar via MCP
Execute agentes da Tess de dentro do Claude, Cursor, Codex ou suas próprias ferramentas internas — sem troca de contexto, sem copiar e colar.
Um endpoint gerenciado mantido pela Tess. Novos recursos aparecem automaticamente; não há cliente para atualizar.
Cada chamada é executada com o token e o workspace de quem chama, herdando suas funções, permissões e limites de créditos existentes.
Construído sobre o protocolo aberto MCP. O mesmo endpoint funciona em todas as plataformas compatíveis — sem integração por fornecedor.
## O que o servidor expõe
O conjunto de ferramentas é **gerado automaticamente a partir da API da Tess** — cada endpoint vira uma ferramenta MCP, então novas capacidades da API aparecem sem qualquer alteração no servidor. Todas as ferramentas estão listadas abaixo, agrupadas por domínio, cada uma com sua própria entrada linkável em [Referência das ferramentas](#tools-reference).
| Domínio | Ferramentas |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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) |
| **Arquivos** | [`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) |
| **Memórias** | [`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 e workspace** | [`deduct_credits_user`](#deduct-credits-user) · [`get_workspace_usage`](#get-workspace-usage) |
Esta lista cobre todas as ferramentas relevantes para uma integração de terceiros. Ferramentas de organização de pastas/chats (usadas internamente pela interface web da Tess) também existem, mas não são documentadas aqui — peça ao seu assistente para "listar as ferramentas disponíveis" e ver o conjunto completo e atual diretamente do seu cliente MCP.
## Antes de começar
Você precisa de duas informações da plataforma Tess:
Gere um token de acesso pessoal em **[Tess AI → Tokens de API](https://tess.im/dashboard/user/tokens)**. É o mesmo token usado em toda a API da Tess — veja o [Quickstart](https://docs.tess.im/api/get-started/quickstart) para detalhes.
O servidor MCP é **escopado por workspace**. Encontre o ID do seu workspace na URL do painel da Tess ou nas configurações do workspace, e use o do workspace cujos agentes você deseja acessar. Cada chamada fica isolada a esse workspace.
Trate seu token de API como uma senha. Ele concede acesso aos agentes e execuções do seu workspace, que podem consumir créditos. Prefira um token dedicado por integração para poder revogá-lo de forma independente.
## Autenticação
As credenciais são enviadas **apenas como cabeçalhos HTTP** — nunca como parâmetros de URL, para que tokens não fiquem em logs ou no histórico do navegador:
```
Authorization: Bearer SEU_TOKEN_DE_API
x-workspace-id: SEU_WORKSPACE_ID
```
Os dois cabeçalhos são obrigatórios em toda requisição. **Obrigatório a partir de 01/09/2026** para o escopo de workspace da API Tess (mesma política do header da API REST). Não há alternativa via parâmetro de URL — seu cliente MCP precisa suportar o envio de cabeçalhos personalizados.
## Conecte sua plataforma
```bash theme={null}
claude mcp add tess --transport http https://mcp.tess.im \
--header "Authorization: Bearer SEU_TOKEN_DE_API" \
--header "x-workspace-id: SEU_WORKSPACE_ID"
```
Depois, em uma sessão: *"Use a Tess para executar o agente de Code Review neste diff."*
Adicione a Tess à sua configuração MCP (no Cursor: **Tools & Integrations → MCP Tools**, ou `~/.cursor/mcp.json`):
```json theme={null}
{
"mcpServers": {
"tess": {
"url": "https://mcp.tess.im",
"headers": {
"Authorization": "Bearer SEU_TOKEN_DE_API",
"x-workspace-id": "SEU_WORKSPACE_ID"
}
}
}
}
```
Adicione um servidor MCP remoto com cabeçalhos em `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.tess]
url = "https://mcp.tess.im"
headers = { Authorization = "Bearer SEU_TOKEN_DE_API", "x-workspace-id" = "SEU_WORKSPACE_ID" }
```
A sintaxe de configuração pode mudar entre versões do Codex CLI — confira `codex mcp --help` ou a documentação atual do Codex se isso não corresponder ao que você vê.
Essas plataformas se conectam a servidores MCP remotos por meio de uma interface de "conector personalizado". Para funcionar com a Tess, a configuração do conector precisa permitir definir **duas** coisas:
* A URL do endpoint: `https://mcp.tess.im`
* **Dois** cabeçalhos personalizados: `Authorization: Bearer SEU_TOKEN_DE_API` e `x-workspace-id: SEU_WORKSPACE_ID`
Algumas interfaces de conector só expõem um único campo de bearer token e não suportam adicionar um segundo cabeçalho personalizado — confira a documentação atual da sua plataforma para saber se cabeçalhos personalizados (além de um bearer token) são suportados para conectores MCP remotos. Se sua plataforma suportar apenas um cabeçalho de autenticação, use um dos clientes com suporte a cabeçalhos acima (Claude Code, Cursor, Codex CLI) ou uma integração personalizada.
## Como funciona a autenticação
O servidor MCP é um **gateway sem estado**. Ele não armazena suas credenciais. A cada requisição ele:
1. Lê seu token de API e o ID do workspace a partir dos cabeçalhos da requisição.
2. Encaminha a chamada para a API da Tess **como você**, exatamente como uma chamada direta à API faria.
3. Retorna o resultado ao seu cliente MCP.
Isso significa que o servidor herda **todos** os controles existentes da sua plataforma:
As chamadas rodam com a identidade do dono do token. Visibilidade de agentes, funções e permissões de recursos são aplicadas pela Tess, sem atalhos.
Cada requisição é vinculada ao `x-workspace-id` enviado. Um token não alcança dados de outro workspace.
As execuções consomem créditos sob os limites e a cobrança do seu workspace — igual à API da Tess.
Revogue um token no painel para cortar instantaneamente qualquer plataforma conectada que o utilize. Sem necessidade de redeploy.
## Referência das ferramentas
list\_agents
Lista os agentes disponíveis no workspace, com busca e paginação.
Busca agentes por título, descrição e descrição longa.
Filtra por tipo de agente.
Número da página para paginação.
Quantidade de agentes por página.
get\_agent
Retorna os detalhes completos de um agente (entradas, tipo, descrição).
O ID do agente.
execute\_agent
Executa um agente com as entradas fornecidas e, opcionalmente, aguarda o resultado.
O ID do agente.
As respostas do agente. Para agentes do tipo chat, inclua um array `messages` (pares `role`/`content`, no mesmo formato do OpenAI Chat Completions).
Quando `true`, aguarda o término da execução e retorna a saída final. Quando `false`, retorna imediatamente para que você consulte a execução depois.
list\_files\_agent
Obtém a lista de arquivos associados a um agente específico.
ID do agente para o qual recuperar os arquivos.
link\_files\_agent
Associa um ou mais arquivos a um agente específico.
ID do agente ao qual vincular os arquivos.
Array de IDs de arquivos a vincular ao agente.
delete\_file\_link\_agent
Remove a associação entre um arquivo específico e um agente.
ID do agente do qual remover o vínculo do arquivo.
ID do arquivo a desvincular do agente.
list\_agent\_responses
Lista respostas de execuções de agentes, com filtros e paginação.
Busca agentes por título.
Filtra pelo ID de execução raiz.
Filtra pelo ID do agente.
Filtra por tipo de agente.
Ordena de forma ascendente ou descendente (`asc`/`desc`).
Página atual.
Quantidade de itens por página.
get\_agent\_response
Obtém uma resposta de execução de agente específica pelo ID.
O ID da execução do agente.
list\_agent\_webhooks
Lista os webhooks registrados para um agente específico.
ID do agente.
Página atual.
Quantidade de itens por página.
create\_agent\_webhook
Registra um novo webhook em um agente específico.
O ID do agente.
A URL de destino do webhook.
Método HTTP usado na chamada do webhook.
Status do webhook (`active`/inativo).
agent\_chat\_completions
Executa um agente através de uma interface compatível com o OpenAI Chat Completions — útil para clientes já integrados no formato da API da OpenAI.
O ID do agente.
Um corpo de requisição no formato do OpenAI Chat Completions.
list\_files
Obtém uma lista paginada de arquivos do workspace, com opções de ordenação.
Número da página para paginação.
Quantidade de itens por página (máx. 100).
Ordem de classificação pelo campo `created_at` (`asc`/`desc`).
upload\_file
Envia um novo arquivo ao workspace e opcionalmente o processa.
O arquivo a enviar.
Se o arquivo deve ser processado imediatamente após o envio.
get\_file
Retorna os detalhes de um arquivo específico.
O ID do arquivo.
delete\_file
Exclui um arquivo do workspace.
O ID do arquivo.
process\_file
Aciona (ou reaciona) o processamento de um arquivo já enviado.
O ID do arquivo.
resolve\_durable\_file\_reference
Resolve uma referência de artefato durável `doc://` (retornada como `ref_url`) em uma URL de download assinada, recém-gerada e de curta duração. A identidade e o escopo do workspace vêm do seu token de API.
A referência de artefato durável a resolver.
list\_memories
Lista as memórias armazenadas no workspace.
Filtra por coleção de memórias.
Número da página para paginação.
Itens por página (máx. 50).
create\_memory
Salva uma nova memória em uma coleção.
A coleção de memórias onde armazenar.
O texto da memória a armazenar (máx. 32.000 caracteres).
update\_memory
Edita uma memória existente.
A memória a atualizar.
Novo texto da memória.
Move a memória para outra coleção.
delete\_memory
Remove uma memória existente.
A memória a excluir.
import\_memories\_text
Aciona uma importação em massa de memórias a partir de texto livre. Assíncrono por padrão.
Se deve bloquear até a importação ser concluída (com timeout limitado) em vez de retornar imediatamente.
get\_memory\_import\_status\_result
Retorna o status e o resumo de uma execução de importação de memórias.
O ID da execução de importação.
list\_webhooks
Lista todos os webhooks do workspace.
Página atual.
Quantidade de itens por página.
delete\_webhook
Exclui um webhook pelo ID.
O ID do webhook.
deduct\_credits\_user
Deduz créditos de um usuário específico com base no fator-base do sistema de créditos e nos parâmetros de cálculo. Destinado a integrações de plataforma que medem o uso de um recurso personalizado.
Identificador do usuário/workspace de quem os créditos serão deduzidos.
Tipo de recurso sendo medido (por exemplo, `image`).
Valor numérico positivo usado no cálculo de créditos.
O ID do workspace.
ID do recurso sendo medido.
Entradas adicionais para o cálculo de créditos.
get\_workspace\_usage
Retorna o uso do workspace detalhado por tipo e intervalo de datas.
Filtro de intervalo de datas predefinido (`1d`/`7d`/`30d`).
Data inicial personalizada (`YYYY-MM-DD`). Use com `end_date`; sobrepõe `range`.
Data final personalizada (`YYYY-MM-DD`). Use com `start_date`; sobrepõe `range`.
Filtra por ID de usuário (requer a permissão `WORKSPACE_DOCUMENTS_READ`).
Filtra por tipo de uso (`chat`, `image`, `text`, `tool_execution`, `connector_calls`, entre outros).
Número da página para paginação.
## Exemplo: execute um agente de ponta a ponta
Após conectar, você pode conduzir um fluxo completo em linguagem natural:
*"Liste meus agentes da Tess"* → o assistente chama [`list_agents`](#list-agents) e mostra o que está disponível.
*"Salve na minha coleção 'Padrões de Engenharia': sempre escreva testes unitários com BDD"* → [`create_memory`](#create-memory).
*"Use o agente de Code Review para revisar esta função, e aguarde o resultado"* → [`execute_agent`](#execute-agent) retorna a saída na hora.
*"Liste minhas memórias"* → [`list_memories`](#list-memories) confirma o que está armazenado para execuções futuras.
## Governança e conformidade
* **Privilégio mínimo** — conecte-se com um token escopado a um único workspace e apenas com as permissões necessárias àquela integração.
* **Auditabilidade** — execuções disparadas via MCP aparecem no histórico e no uso do seu workspace na Tess, como qualquer chamada de API.
* **Sem armazenamento de credenciais** — o gateway é sem estado; os tokens ficam apenas na configuração do seu cliente MCP.
* **Revogação centralizada** — desativar um token no painel bloqueia imediatamente todas as plataformas que o utilizam.
## Solução de problemas
Confirme que seu cliente usa o transporte **Streamable HTTP** (remoto) em vez de um comando local/stdio, e que está apontado diretamente para `https://mcp.tess.im` (sem caminho extra).
Os dois cabeçalhos são obrigatórios em toda requisição — `Authorization: Bearer SEU_TOKEN_DE_API` e `x-workspace-id: SEU_WORKSPACE_ID`. Não há opção via parâmetro de URL; confirme que seu cliente suporta o envio de cabeçalhos personalizados e que o token está ativo no painel.
O ID do workspace está ausente, malformado, ou o token não tem acesso a ele. Confirme que o cabeçalho `x-workspace-id` está definido e corresponde a um workspace acessível pelo seu token.
Alguns agentes exigem entradas específicas. Agentes do tipo chat, por exemplo, esperam um array `messages` dentro de `body`. Peça ao assistente para inspecionar os campos do agente ([`get_agent`](#get-agent)), ou verifique o agente na plataforma Tess.
## Recursos
* [Model Context Protocol — site oficial](https://modelcontextprotocol.io)
* [Como criar um Token de API na Tess AI](https://docs.tess.im/api/get-started/quickstart)