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

# Custom API

> Beta. Monta um servidor MCP a partir de uma spec OpenAPI 3 depois que um admin liga Custom API to MCP.

> [!WARNING]
>
> **Custom API** é beta. Fica desligado até um admin ligar **Custom API to MCP**.

Custom API monta um servidor MCP a partir de uma descrição OpenAPI 3 de uma API HTTP. O servidor mostra o selo **Custom API**. Esse selo não tem tradução. Chats e agentes chamam esse servidor como qualquer outro na aba **MCP**. Veja [Custom MCP](https://docs.tess.im/pt/mcp-custom.md).

## Ligar

Abra a página de admin com o título **Feature Toggles**. Esse título não tem tradução. O link de volta é **Voltar ao painel**.

Ligue **Custom API to MCP**. O rótulo não tem tradução e traz um selo beta. O interruptor fica desmarcado quando a configuração não existe. Criar e atualizar dependem desse interruptor. Ele é um feature toggle da plataforma, não um controle nas configurações do workspace.

## Onde montar

**Build from Custom API** fica no menu de adicionar de MCP Plugins. A mesma tela entra no diálogo de Conectores, na aba **MCP**.

O controle de adicionar muda se já existe algum servidor:

* Nenhum ainda: **Add custom MCP**. Esse rótulo não tem tradução.
* Pelo menos um: **Novo servidor MCP**, com a linha **Adicionar servidor MCP personalizado**.

O menu também oferece **Import by JSON** e **Direct configuration**. Esses dois rótulos não têm tradução. **Build from Custom API** é o terceiro item, e só aparece com o interruptor ligado e se você pode criar servidores MCP.

Você cria um se pode escrever plugins MCP, ou se pode gerenciá-los. O dono do workspace pode gerenciá-los.

## O que preencher

O título do diálogo de criação é **Build from Custom API**. **Build** fica desabilitado até o nome, a URL base, uma especificação e uma credencial estarem preenchidos. Enquanto salva, o botão mostra **Building...**. Os dois rótulos do botão não têm tradução.

| Campo | Obrigatório | O que o diálogo aceita |
| - | - | - |
| **Server Name** | Sim | Até 255 caracteres. Placeholder **e.g., My Custom Server**. O rótulo e o placeholder não têm tradução. |
| **Base URL** | Sim | Uma URL `http` ou `https`, até 2048 caracteres. Placeholder `https://api.provider.com/v1`. Um endereço bloqueado mostra **A URL base não é permitida.** O rótulo não tem tradução. |
| **API specification** | Sim | **URL**, **Upload** ou **Colar**. Veja abaixo. |
| **Autenticação** | Sim | Um de quatro tipos. O padrão é **Chave de API**. |
| **Notes** | Não | Até 1000 caracteres. Placeholder **Which operations matter, what must not become a tool**. As notas ficam gravadas no servidor. Elas não tiram operações da spec. O rótulo e o placeholder não têm tradução. |
| **Compartilhar com o workspace** | Não | Um interruptor. Veja o compartilhamento abaixo. |

### Especificação da API

Só OpenAPI 3. O campo `openapi` precisa ser `3` ou começar com `3.`. O documento precisa de um objeto `info`, um objeto `paths` que não esteja vazio e pelo menos uma operação. Uma operação é `get`, `put`, `post`, `delete`, `patch`, `head`, `options` ou `trace`.

Se você nunca viu um arquivo desses, comece por [O que é uma especificação OpenAPI e como conseguir a sua](https://docs.tess.im/pt/openapi-spec.md).

| Origem | O que você informa |
| - | - |
| **URL** | **Spec URL**, um endereço `http` ou `https` de até 2048 caracteres. Um endereço bloqueado mostra **A URL da especificação da API não é permitida.** **Spec URL** não tem tradução. |
| **Upload** | `.json`, `.yaml` ou `.yml`, até 2 MB. A área diz **Arraste e solte ou clique para escolher** e **Upload an OpenAPI/Swagger file (JSON or YAML)**. A segunda linha não tem tradução. Uma extensão errada mostra **Apenas arquivos .json, .yaml e .yml são suportados**. Acima de 2 MB no navegador mostra **O arquivo é grande demais (máx. 2 MB)**. |
| **Colar** | O texto da spec. Placeholder **Paste your OpenAPI/Swagger spec**, sem tradução. |

A spec guardada também tem limite de 2 MB. Um documento maior mostra **O arquivo passa do limite de 2 MB. Envie uma versão menor, só com as partes da API que você vai usar.**

### Autenticação

| Tipo | O que preencher |
| - | - |
| **Token Bearer** | O token, até 4096 caracteres. Placeholder **API key or bearer token**, sem tradução. |
| **Chave de API** | O mesmo campo de segredo. Este é o padrão. |
| **Header Personalizado** | O segredo, mais **Header name, e.g. X-API-Key**. O nome do header é obrigatório e não tem tradução. |
| **Token (obtido por request)** | A Tess pede um token e o renova. Veja a seção seguinte. |

### Token obtido por request

O diálogo diz que a Tess solicita um token com a request abaixo e o renova quando expira. Um segredo entra como `{{secret.name}}` e o token como `{{access_token}}`.

* **Segredos**. Pelo menos um. Até 20. Cada nome usa letras, números e sublinhado, até 64 caracteres. Um nome inválido mostra **Os nomes dos segredos só podem ter letras, números e sublinhado (\_).** Placeholders **Nome, ex.: api\_key** e **Valor**. **Adicionar segredo** inclui uma linha.
* **Request do token**. **Método** é **POST** ou **GET**. **URL do token, ex.: /v1/auth** é uma URL `http` ou `https` completa, ou um caminho que começa com `/`. Um caminho inválido mostra **Use uma URL http(s) completa ou um caminho começando com /.** Uma URL bloqueada mostra **A URL do token não é permitida.** Headers opcionais, até 20. Corpo opcional, até 16384 caracteres.
* **Resposta do token**. **Campo do token, ex.: access\_token** é obrigatório. **Campo de validade (segundos), ex.: expires\_in** é obrigatório. Cada um é um nome com pontos, como `access_token` ou `data.expires_in`.
* **Headers enviados em toda chamada**. Pelo menos um, até 20. Um deles precisa conter `{{access_token}}`. Se não contiver, o diálogo mostra **Use `{{access_token}}` em pelo menos um header enviado em toda chamada.** Usar `{{access_token}}` na própria request do token mostra **`{{access_token}}` só pode ser usado nos headers enviados em toda chamada.** Um placeholder que não corresponde a um segredo cita esse placeholder.

## O que vira ferramenta

Cada operação HTTP em `paths` vira uma ferramenta. Não há uma lista de permissão separada para uma spec Custom API, e **Notes** não removem operações. A Tess dá o nome da ferramenta a partir da operação. O cartão do servidor lista essas ferramentas, e você liga ou desliga cada uma para você.

## Uma spec pequena

Cole isto em **Colar**, com **Base URL** `https://api.example.com`. É um GET. **Autenticação** ainda pede uma credencial, mesmo que a API seja pública. Use um valor que a API ignore, ou o header que a API realmente verifica.

```json theme={null}
{
  "openapi": "3.0.3",
  "info": { "title": "Status", "version": "1.0.0" },
  "paths": {
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Read the service status",
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}
```

## Compartilhamento

Na criação, **Compartilhar com o workspace** começa **ligado** se você pode governar MCP (dono do workspace, ou permissão para gerenciar plugins MCP). Começa **desligado**, e o controle fica desabilitado, se você não pode. A dica do controle desabilitado é **Compartilhar com o workspace exige permissão de governança de MCP**.

Você muda isso depois no cartão do servidor, não em **Editar**. A dica do cartão, para quem pode alterar, é **Compartilhado — clique para alterar** ou **Pessoal — clique para compartilhar**. Confirmar o compartilhamento diz **Todos os membros do workspace poderão usar ":name".** O botão é **Compartilhar**. Tornar pessoal diz **Outros membros perderão o acesso a ":name".** O botão é **Tornar pessoal**.

Um servidor pessoal fica com quem o criou. Um servidor compartilhado pode ser usado pelos membros do workspace. A adesão no chat é a mesma dos outros servidores Custom MCP: [Custom MCP](https://docs.tess.im/pt/mcp-custom.md).

## Usar

No chat, abra Conectores e a aba **MCP**. Ligue o servidor e ligue as ferramentas que quiser. No Agent Studio, adicione esse servidor MCP à política de conectores do agente do mesmo jeito que qualquer outro servidor Custom MCP.

## Editar e excluir

O botão do menu no cartão tem o título **Mais ações**. **Editar** abre um diálogo com o título **Configuração do MCP**. **Excluir** remove o servidor. **Excluir** aparece quando você pode excluir: quem criou um servidor pessoal, se ainda pode criar servidores MCP, ou quem pode governar MCP. Quem governa também pode excluir o servidor pessoal de outra pessoa.

Na edição você altera o nome, o ícone, a URL base, a autenticação, a especificação e a credencial.

* Deixe a especificação vazia: **Deixe em branco para manter a especificação atual.**
* Mude o endereço ou a autenticação: é preciso enviar a especificação de novo. **Envie a especificação da API de novo para alterar o endereço ou a autenticação.**
* Deixe a credencial em branco: **Deixe em branco para manter a credencial atual.** Trocar para **Token (obtido por request)** e enviar uma spec nova exige preencher os segredos e a request do token de novo: **Para enviar uma nova especificação, preencha de novo os segredos e a requisição do token.**
* **Ícone** (**opcional**). Placeholder **Cole a URL**. Um endereço HTTPS, ou vazio para limpar. Qualquer outro mostra **O ícone precisa ser um endereço HTTPS.**

**Editar** não inclui **Compartilhar com o workspace**. Mais sobre a edição: [Editar um servidor Custom MCP](https://docs.tess.im/pt/mcp-custom.md#editar-um-servidor-custom-mcp).

## Quando uma spec é recusada

Uma lista em linguagem simples está em [O que é uma especificação OpenAPI e como conseguir a sua](https://docs.tess.im/pt/openapi-spec.md).

| O que você vê | O que mudar |
| - | - |
| **Este arquivo está num formato antigo (Swagger 2.0). Envie a versão OpenAPI 3, ou peça a quem fornece a API para atualizá-la.** | O arquivo é Swagger 2. Envie OpenAPI 3. |
| **Este arquivo não parece ser uma documentação de API válida (OpenAPI). Confira se enviou o arquivo certo.** | Não é OpenAPI 3, falta `info`, não há `paths`, ou não há operações. Também cobre uma spec que não é um objeto JSON ou YAML, JSON ou YAML inválido, ou aninhamento além de 64 níveis. |
| **Não conseguimos ler este arquivo. Ele usa um atalho do formato YAML que ainda não aceitamos. Envie a versão em JSON da documentação da API — normalmente um link ou arquivo terminado em openapi.json ou swagger.json. Se não encontrar, peça a quem fornece a API para exportar a documentação em JSON.** | O YAML usa âncoras ou aliases. Envie JSON. |
| **O arquivo passa do limite de 2 MB. Envie uma versão menor, só com as partes da API que você vai usar.** | Reduza a spec. |
| **O endereço da API não é válido ou não pode ser acessado pela internet. Confira o endereço informado.** | Corrija **Base URL**. |
| **A URL base não é permitida.** ou **A URL da especificação da API não é permitida.** | O endereço não passou na checagem de saída. Use uma URL `http` ou `https` pública. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.