Trama para agentes de IA

Como funciona

O servidor fala Streamable HTTP. Ele não guarda nada: cada chamada de ferramenta vira requisições à API do Trama com as suas credenciais, então o agente vê os quadros que você vê e só pode alterar o que você mesmo poderia. Há duas formas de entrar.

Claude

Os dois se conectam com OAuth: adicione a URL uma vez e depois aprove o acesso no navegador.

claude mcp add --transport http trama https://mcp.ontrama.com/mcp

{
  "mcpServers": {
    "trama": {
      "type": "http",
      "url": "https://mcp.ontrama.com/mcp"
    }
  }
}

Cursor

Adicione o servidor em ~/.cursor/mcp.json (todos os projetos) ou .cursor/mcp.json (um projeto), ou pelas configurações de MCP do Cursor. O Cursor descobre o OAuth sozinho e abre o navegador para você aprovar.

{
  "mcpServers": {
    "trama": {
      "url": "https://mcp.ontrama.com/mcp"
    }
  }
}

Outros clientes

Qualquer cliente com suporte a Streamable HTTP e à descoberta de OAuth funciona só com a URL. O que ele precisa saber:

O que acontece quando um cliente se conecta pela primeira vez:

1. Ele chama POST /mcp sem token e recebe 401 com um header WWW-Authenticate que aponta para os metadados do recurso protegido.
2. Os metadados indicam o servidor de autorização, https://api.ontrama.com; o cliente lê o /.well-known/oauth-authorization-server dele.
3. Ele se registra com POST /oauth2/register.
4. Ele abre https://ontrama.com/oauth2/authorize no seu navegador. Você entra, vê o que ele pede e aprova.
5. Ele troca o código e o seu PKCE verifier em POST /oauth2/token por um access token (lxt_at_…, 7 dias) e um refresh token que é rotacionado a cada uso.
6. A partir daí, ele chama POST /mcp com Authorization: Bearer lxt_at_….

O servidor é stateless e só responde a POST; GET e DELETE em /mcp retornam 405.

Token pessoal

Para clientes que não fazem OAuth. Crie um token em ConfiguraçõesAPI e MCP e envie-o como Bearer token. O servidor separa a sua chave de API e o seu segredo antes de chamar a API.

{
  "mcpServers": {
    "trama": {
      "url": "https://mcp.ontrama.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PERSONAL_TOKEN"
      }
    }
  }
}

claude mcp add --transport http trama https://mcp.ontrama.com/mcp \
  --header "Authorization: Bearer YOUR_PERSONAL_TOKEN"

Ferramentas

O servidor tem 38 ferramentas, todas construídas sobre operações da API que tokens OAuth podem usar. As ferramentas recebem ids, nomes, chaves como ACME-42 ou links; quando um nome pode se referir a várias coisas, a ferramenta responde com os candidatos em vez de adivinhar. Os agentes buscam ou listam suas tarefas, leem uma tarefa ou a página que importa e então agem; especificações e decisões vão para páginas vinculadas às tarefas.

update_task_metadata também lê a tarefa de volta, por isso precisa de boards.read também. As relações que ela adiciona só se acumulam; um link de duplicata pode ser removido passando duplicate_of: null. Os agentes vinculam tarefas e documentos em Markdown, como [ACME-12 Fix the login](/tasks/123) ou [Release plan](/documents/45), e o Trama mostra os backlinks dos dois lados.

Solução de problemas

Veja também