Servidor MCP - Tess AI Docs

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.

Servidor MCP da Tess

Esta página. Exponha agentes, arquivos e memórias da Tess para Claude, Cursor, Codex ou qualquer cliente MCP.

Custom MCP

O outro sentido: conecte servidores MCP externos ao chat e aos agentes da Tess, com escopo pessoal ou compartilhado.

Por que conectar via MCP

Use a Tess onde sua equipe já trabalha

Execute agentes da Tess de dentro do Claude, Cursor, Codex ou suas próprias ferramentas internas — sem troca de contexto, sem copiar e colar.

Zero instalação, sempre atualizado

Um endpoint gerenciado mantido pela Tess. Novos recursos aparecem automaticamente; não há cliente para atualizar.

Governado pelo seu workspace

Cada chamada é executada com o token e o workspace de quem chama, herdando suas funções, permissões e limites de créditos existentes.

Padronizado e portátil

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 é uma lista explícita da API pública da Tess — os mesmos endpoints documentados em Visão geral da API. Novas capacidades da API só aparecem como ferramentas MCP depois de entrar nessa superfície pública. 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.

Domínio	Ferramentas
Agentes	`list_agents` · `get_agent` · `execute_agent` · `list_files_agent` · `link_files_agent` · `delete_file_link_agent` · `get_agent_response` · `list_agent_webhooks` · `create_agent_webhook`
Arquivos	`list_files` · `upload_file` · `get_file` · `delete_file` · `process_file`
Memórias	`list_memories` · `create_memory` · `update_memory` · `delete_memory`
Coleções de memória	`list_memory_collections` · `create_memory_collection` · `update_memory_collection` · `delete_memory_collection`
Webhooks	`list_webhooks` · `delete_webhook`
Workspace e auditoria	`get_workspace_usage` · `list_audit_events`

A lista corresponde à API pública. Endpoints internos só de sessão nunca viram ferramentas MCP. Peça ao assistente para listar as ferramentas disponíveis se quiser confirmar o conjunto ao vivo no seu cliente.

Antes de começar

Você precisa de duas informações da plataforma Tess:

Seu token de API

Gere um token de acesso pessoal em Tess AI → Tokens de API. É o mesmo token usado em toda a API da Tess — veja o Quickstart para detalhes.

O ID do seu workspace

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

Claude Code
Cursor / VS Code
Codex CLI
Claude Desktop / ChatGPT / outros

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.”Configurações JSON remotas precisam de type definido como http (ou streamable-http). Uma url sem type é ignorada como servidor stdio quebrado.

Adicione a Tess à sua configuração MCP (no Cursor: Tools & Integrations → MCP Tools, ou ~/.cursor/mcp.json):

{
  "mcpServers": {
    "tess": {
      "url": "https://mcp.tess.im",
      "headers": {
        "Authorization": "Bearer SEU_TOKEN_DE_API",
        "x-workspace-id": "SEU_WORKSPACE_ID"
      }
    }
  }
}

Prefira interpolar uma variável de ambiente para o token em vez de gravá-lo em texto puro. O Cursor resolve interpolação de env em url e headers.

Adicione um servidor MCP remoto com cabeçalhos em ~/.codex/config.toml:

[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:

Lê seu token de API e o ID do workspace a partir dos cabeçalhos da requisição.
Encaminha a chamada para a API da Tess como você, exatamente como uma chamada direta à API faria.
Retorna o resultado ao seu cliente MCP.

Isso significa que o servidor herda todos os controles existentes da sua plataforma:

Identidade e permissões

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.

Isolamento de workspace

Cada requisição é vinculada ao x-workspace-id enviado. Um token não alcança dados de outro workspace.

Governança de créditos

As execuções consomem créditos sob os limites e a cobrança do seu workspace — igual à API da Tess.

Acesso revogável

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.

string

Busca agentes por título, descrição e descrição longa.

string

Filtra por tipo de agente.

integer

padrão:"1"

Número da página para paginação.

integer

padrão:"15"

Quantidade de agentes por página.

get_agent

Retorna os detalhes completos de um agente (entradas, tipo, descrição).

string | integer

obrigatório

O ID do agente.

execute_agent

Executa um agente com as entradas fornecidas e, opcionalmente, aguarda o resultado.

string | integer

obrigatório

O ID do agente.

object

obrigatório

As respostas do agente. Para agentes do tipo chat, inclua um array messages (pares role/content, no mesmo formato do OpenAI Chat Completions).

boolean

padrão:"false"

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.

integer

obrigatório

ID do agente para o qual recuperar os arquivos.

link_files_agent

Associa um ou mais arquivos a um agente específico.

integer

obrigatório

ID do agente ao qual vincular os arquivos.

integer[]

obrigatório

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.

integer

obrigatório

ID do agente do qual remover o vínculo do arquivo.

integer

obrigatório

ID do arquivo a desvincular do agente.

get_agent_response

Obtém uma resposta de execução de agente específica pelo ID.

string | integer

obrigatório

O ID da execução do agente.

list_agent_webhooks

Lista os webhooks registrados para um agente específico.

integer

obrigatório

ID do agente.

integer

padrão:"1"

Página atual.

integer

padrão:"15"

Quantidade de itens por página.

create_agent_webhook

Registra um novo webhook em um agente específico.

string | integer

obrigatório

O ID do agente.

string

A URL de destino do webhook.

string

padrão:"POST"

Método HTTP usado na chamada do webhook.

string

padrão:"active"

Status do webhook (active/inativo).

list_files

Obtém uma lista paginada de arquivos do workspace, com opções de ordenação.

integer

padrão:"1"

Número da página para paginação.

integer

padrão:"15"

Quantidade de itens por página (máx. 100).

string

padrão:"desc"

Ordem de classificação pelo campo created_at (asc/desc).

upload_file

Envia um novo arquivo ao workspace e opcionalmente o processa.

binary

obrigatório

O arquivo a enviar.

boolean

padrão:"false"

Se o arquivo deve ser processado imediatamente após o envio.

get_file

Retorna os detalhes de um arquivo específico.

integer

obrigatório

O ID do arquivo.

delete_file

Exclui um arquivo do workspace.

integer

obrigatório

O ID do arquivo.

process_file

Aciona (ou reaciona) o processamento de um arquivo já enviado.

integer

obrigatório

O ID do arquivo.

list_memories

Lista as memórias armazenadas no workspace.

integer

Filtra por coleção de memórias.

integer

padrão:"1"

Número da página para paginação.

integer

padrão:"10"

Itens por página (máx. 50).

create_memory

Salva uma nova memória em uma coleção.

integer

A coleção de memórias onde armazenar.

string

O texto da memória a armazenar (máx. 32.000 caracteres).

update_memory

Edita uma memória existente.

integer

obrigatório

A memória a atualizar.

string

Novo texto da memória.

integer

Move a memória para outra coleção.

delete_memory

Remove uma memória existente.

integer

obrigatório

A memória a excluir.

list_memory_collections

Lista as coleções de memória do workspace.

string

Filtra coleções por nome.

integer

padrão:"1"

Número da página.

integer

padrão:"12"

Itens por página (1–50).

create_memory_collection

Cria uma coleção de memória.

string

obrigatório

Nome da coleção.

string

Descrição opcional.

update_memory_collection

Atualiza uma coleção de memória.

integer

obrigatório

A coleção a atualizar.

string

Novo nome.

string

Nova descrição.

delete_memory_collection

Exclui uma coleção de memória.

integer

obrigatório

A coleção a excluir.

list_webhooks

Lista todos os webhooks do workspace.

integer

padrão:"1"

Página atual.

integer

padrão:"15"

Quantidade de itens por página.

delete_webhook

Exclui um webhook pelo ID.

integer

obrigatório

O ID do webhook.

get_workspace_usage

Retorna o uso do workspace detalhado por tipo e intervalo de datas.

string

Filtro de intervalo de datas predefinido (1d/7d/30d).

string

Data inicial personalizada (YYYY-MM-DD). Use com end_date; sobrepõe range.

string

Data final personalizada (YYYY-MM-DD). Use com start_date; sobrepõe range.

integer

Filtra por ID de usuário (requer a permissão WORKSPACE_DOCUMENTS_READ).

string

Filtra por tipo de uso (chat, image, text, tool_execution, connector_calls, entre outros).

integer

padrão:"1"

Número da página para paginação.

list_audit_events

Busca eventos de auditoria do workspace para ingestão em SIEM. A janela de tempo é obrigatória e não pode ultrapassar 30 dias.

string

obrigatório

Início da janela (YYYY-MM-DD).

string

obrigatório

Fim da janela (YYYY-MM-DD). Deve estar a no máximo 30 dias de from.

integer

padrão:"50"

Máximo de eventos por página (1–200).

string

Cursor opaco de paginação da resposta anterior.

string

Filtra pela origem (auditable ou activity).

string

Filtra por tipo de evento.

integer

Filtra pelo ator.

list_audit_events

Busca eventos de auditoria do workspace para ingestão em SIEM. A janela de tempo é obrigatória e não pode ultrapassar 30 dias.

string

obrigatório

Início da janela (YYYY-MM-DD).

string

obrigatório

Fim da janela (YYYY-MM-DD). Deve estar a no máximo 30 dias de from.

integer

padrão:"50"

Máximo de eventos por página (1–200).

string

Cursor opaco de paginação da resposta anterior.

string

Filtra pela origem (auditable ou activity).

string

Filtra por tipo de evento.

integer

Filtra pelo ator.

Exemplo: execute um agente de ponta a ponta

Após conectar, você pode conduzir um fluxo completo em linguagem natural:

Descubra os agentes

“Liste meus agentes da Tess” → o assistente chama list_agents e mostra o que está disponível.

Capture contexto como memória

“Salve na minha coleção ‘Padrões de Engenharia’: sempre escreva testes unitários com BDD” → create_memory.

Execute um agente

“Use o agente de Code Review para revisar esta função, e aguarde o resultado” → execute_agent retorna a saída na hora.

Reutilize depois

“Liste minhas memórias” → 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

O cliente conecta mas nenhuma ferramenta aparece

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). No Claude Code, entradas JSON remotas também precisam de type definido como http.

Erros 401 / 'não autorizado'

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.

Erros 404 ou de 'workspace'

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.

Um agente falha ao executar

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), ou verifique o agente na plataforma Tess.

Recursos

Custom MCP — conecte servidores MCP externos à Tess
Compartilhamento e permissões
Boas práticas de MCP
Model Context Protocol — site oficial
Como criar um Token de API na Tess AI

Servidor MCP da Tess

Custom MCP

​Por que conectar via MCP

Use a Tess onde sua equipe já trabalha

Zero instalação, sempre atualizado

Governado pelo seu workspace

Padronizado e portátil

​O que o servidor expõe

​Antes de começar

​Autenticação

​Conecte sua plataforma

​Como funciona a autenticação

Identidade e permissões

Isolamento de workspace

Governança de créditos

Acesso revogável

​Referência das ferramentas

​list_agents

​get_agent

​execute_agent

​list_files_agent

​link_files_agent

​delete_file_link_agent

​get_agent_response

​list_agent_webhooks

​create_agent_webhook

​list_files

​upload_file

​get_file

​delete_file

​process_file

​list_memories

​create_memory

​update_memory

​delete_memory

​list_memory_collections

​create_memory_collection

​update_memory_collection

​delete_memory_collection

​list_webhooks

​delete_webhook

​get_workspace_usage

​list_audit_events

​list_audit_events

​Exemplo: execute um agente de ponta a ponta

​Governança e conformidade

​Solução de problemas

​Recursos

Por que conectar via MCP

O que o servidor expõe

Antes de começar

Autenticação

Conecte sua plataforma

Como funciona a autenticação

Referência das ferramentas

list_agents

get_agent

execute_agent

list_files_agent

link_files_agent

delete_file_link_agent

get_agent_response

list_agent_webhooks

create_agent_webhook

list_files

upload_file

get_file

delete_file

process_file

list_memories

create_memory

update_memory

delete_memory

list_memory_collections

create_memory_collection

update_memory_collection

delete_memory_collection

list_webhooks

delete_webhook

get_workspace_usage

list_audit_events

list_audit_events

Exemplo: execute um agente de ponta a ponta

Governança e conformidade

Solução de problemas

Recursos