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.

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 é 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.

Domínio	Ferramentas
Agentes	`list_agents` · `get_agent` · `execute_agent` · `list_files_agent` · `link_files_agent` · `delete_file_link_agent` · `list_agent_responses` · `get_agent_response` · `list_agent_webhooks` · `create_agent_webhook` · `agent_chat_completions`
Arquivos	`list_files` · `upload_file` · `get_file` · `delete_file` · `process_file` · `resolve_durable_file_reference`
Memórias	`list_memories` · `create_memory` · `update_memory` · `delete_memory` · `import_memories_text` · `get_memory_import_status_result`
Webhooks	`list_webhooks` · `delete_webhook`
Créditos e workspace	`deduct_credits_user` · `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:

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.”

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"
      }
    }
  }
}

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.

list_agent_responses

Lista respostas de execuções de agentes, com filtros e paginação.

string

Busca agentes por título.

integer

Filtra pelo ID de execução raiz.

integer

Filtra pelo ID do agente.

string

Filtra por tipo de agente.

string

padrão:"asc"

Ordena de forma ascendente ou descendente (asc/desc).

integer

padrão:"1"

Página atual.

integer

padrão:"15"

Quantidade de itens por página.

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).

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.

string | integer

obrigatório

O ID do agente.

object

obrigatório

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.

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.

resolve_durable_file_reference

Resolve uma referência de artefato durável doc://<universal_id> (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.

string

obrigatório

A referência de artefato durável a resolver.

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.

import_memories_text

Aciona uma importação em massa de memórias a partir de texto livre. Assíncrono por padrão.

boolean

padrão:"false"

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.

string | integer

obrigatório

O ID da execução de importação.

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.

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.

integer

obrigatório

Identificador do usuário/workspace de quem os créditos serão deduzidos.

string

obrigatório

Tipo de recurso sendo medido (por exemplo, image).

number

obrigatório

Valor numérico positivo usado no cálculo de créditos.

integer

O ID do workspace.

string

ID do recurso sendo medido.

object

Entradas adicionais para o cálculo de créditos.

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.

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).

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.

​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

​list_agent_responses

​get_agent_response

​list_agent_webhooks

​create_agent_webhook

​agent_chat_completions

​list_files

​upload_file

​get_file

​delete_file

​process_file

​resolve_durable_file_reference

​list_memories

​create_memory

​update_memory

​delete_memory

​import_memories_text

​get_memory_import_status_result

​list_webhooks

​delete_webhook

​deduct_credits_user

​get_workspace_usage

​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

list_agent_responses

get_agent_response

list_agent_webhooks

create_agent_webhook

agent_chat_completions

list_files

upload_file

get_file

delete_file

process_file

resolve_durable_file_reference

list_memories

create_memory

update_memory

delete_memory

import_memories_text

get_memory_import_status_result

list_webhooks

delete_webhook

deduct_credits_user

get_workspace_usage

Exemplo: execute um agente de ponta a ponta

Governança e conformidade

Solução de problemas

Recursos