> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexxible.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conectar os seus próprios agentes

> Como conectar Claude, Cursor, Copilot ou qualquer cliente MCP ao Flexxible KB com uma chave de agente, e o que eles podem fazer por meio do servidor MCP e da API REST.

Além dos agentes do Flexxible Assist, você pode conectar à base de conhecimento os seus próprios agentes de IA: Claude, Cursor, GitHub Copilot no VS Code ou qualquer cliente compatível com MCP. Um agente conectado busca, lê e escreve páginas assim como o Teammate, e tudo o que ele faz fica registrado.

> [!NOTE]
>
> Esta página trata do servidor MCP do Flexxible KB, que dá acesso à base de conhecimento. O [servidor MCP da Flexxible](https://docs.flexxible.com/pt-BR/features/integrations/mcp.md), que dá acesso a workspaces, sessões e operações da plataforma, é um serviço diferente, com outro endereço e outra autorização.

## Como funciona

* **Um agente é uma identidade da sua organização.** Você o cria em **Configurações** → **Agentes**, com um nome, como "Claude Code".
* **Cada agente tem as suas chaves.** Uma chave para cada lugar em que ele é executado, para que você possa revogá-las uma a uma.
* **A chave é enviada como token Bearer.** Quem tiver a chave atua como esse agente na sua organização.
* **Tudo fica em nome dele.** As suas alterações aparecem no Histórico com o nome do agente, e as suas chamadas em **Atividade**.

Somente os proprietários e os administradores criam agentes e gerenciam as suas chaves.

## Criar um agente e a sua chave

**1. Crie o agente**

Em **Configurações** → **Agentes**, em **Seus agentes**, selecione **Novo agente**, dê um nome a ele e selecione **Criar agente**.

**2. Crie uma chave**

Abra o agente, selecione **Nova chave** e dê a ela o nome do lugar em que será usada, por exemplo "Claude no notebook da Marta". Selecione **Criar chave**.

**3. Copie a chave**

Copie a chave nesse momento: ela não será exibida novamente. **Copiar para Claude Code** copia diretamente o comando de configuração com a chave incluída.

> [!WARNING]
>
> Trate uma chave de agente como uma senha. Não a cole em uma conversa com o assistente, em uma página nem em um repositório. Se ela vazar, revogue-a a partir do agente: o que a estiver usando deixará de funcionar na hora.

## Endereços

Os endereços da sua organização são exibidos em **Configurações** → **Agentes** → **Conectar um agente**, com um botão para copiar cada um.

| O quê | Endereço |
| - | - |
| Servidor MCP | `https://kb.flexxible.com/mcp` |
| API REST | `https://kb.flexxible.com/api/v1` |
| Especificação OpenAPI | `https://kb.flexxible.com/api/v1/openapi.json` |
| Guia para agentes | `https://kb.flexxible.com/llms.txt` |

Em todos os casos, a chave é enviada no cabeçalho `Authorization: Bearer <clave de agente>`.

![Seção Conectar um agente das configurações: endereços do servidor MCP e da API REST, e a configuração para Claude Code, Claude Desktop, Cursor, VS Code e curl.](https://mintcdn.com/flexxible/luynIZmFTttZPpU9/images/features/kb-connect-agent.png?fit=max\&auto=format\&n=luynIZmFTttZPpU9\&q=85\&s=ec9ca24b43028f38e1e41f1f69d4cd48)

## Configurar o cliente

A seção **Como conectar** das configurações oferece a configuração pronta para copiar. Substitua `<clave de agente>` pela sua chave.

> [tab] Claude Code
>
> Execute o comando em um terminal. Adicione `--scope user` para tê-lo em todos os projetos.
>
> ```bash theme={null}
> claude mcp add --transport http flx-kb https://kb.flexxible.com/mcp --header "Authorization: Bearer <clave de agente>"
> ```

> [tab] Claude Desktop
>
> Em **Customize** → **Connectors** → **Add custom connector**, escreva o endereço do servidor MCP, escolha **No sign-in** e, em **Request headers**, adicione o cabeçalho `authorization` com o valor `Bearer <clave de agente>`.
>
> Se você não vir a seção **Request headers**, adicione o servidor ao arquivo `claude_desktop_config.json`:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "flx-kb": {
>       "command": "npx",
>       "args": [
>         "-y",
>         "mcp-remote@0.15.2",
>         "https://kb.flexxible.com/mcp",
>         "--header",
>         "Authorization:${AUTH_HEADER}"
>       ],
>       "env": {
>         "AUTH_HEADER": "Bearer <clave de agente>"
>       }
>     }
>   }
> }
> ```

> [tab] Cursor
>
> Adicione-o a `.cursor/mcp.json` no projeto, ou a `~/.cursor/mcp.json` para todos os projetos. Coloque a chave na variável de ambiente `FLX_KB_KEY` do seu shell, para que ela não fique no arquivo.
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "flx-kb": {
>       "url": "https://kb.flexxible.com/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:FLX_KB_KEY}"
>       }
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Adicione-o a `.vscode/mcp.json` no projeto. O VS Code pede a chave uma vez e a guarda de forma segura.
>
> ```json theme={null}
> {
>   "inputs": [
>     {
>       "type": "promptString",
>       "id": "flx-kb-key",
>       "description": "FLX KB agent key",
>       "password": true
>     }
>   ],
>   "servers": {
>     "flx-kb": {
>       "type": "http",
>       "url": "https://kb.flexxible.com/mcp",
>       "headers": {
>         "Authorization": "Bearer ${input:flx-kb-key}"
>       }
>     }
>   }
> }
> ```

> [tab] curl
>
> A API REST: busca e, depois, lê uma página como Markdown.
>
> ```bash theme={null}
> curl "https://kb.flexxible.com/api/v1/search?q=vpn" -H "Authorization: Bearer <clave de agente>"
> curl "https://kb.flexxible.com/api/v1/pages/vpn.md" -H "Authorization: Bearer <clave de agente>"
> ```

Depois de conectado, teste com uma pergunta como: *"Qual cliente de VPN nós usamos? Busque no flx-kb."*

## Ferramentas do servidor MCP

O servidor MCP publica ferramentas com nomes e descrições pensados para modelos de IA, e inclui instruções sobre como utilizá-las.

| Área | Ferramentas | O que permitem |
| - | - | - |
| Buscar e ler | `kb_search`, `kb_fetch`, `kb_list_pages`, `kb_page_tree`, `kb_list_spaces` | Buscar por significado e por palavras, ler uma página como Markdown e percorrer a árvore e os espaços. |
| Alterações | `kb_page_history`, `kb_recent_changes`, `kb_undo_change` | Consultar o histórico de uma página e as últimas alterações, e desfazer uma alteração. |
| Escrever | `kb_create_page`, `kb_edit_page` | Criar uma página, editá-la com alterações precisas, alterar o seu título ou movê-la. |
| Comentários | `kb_list_comments`, `kb_comment`, `kb_resolve_comment` | Ler os comentários de uma página, comentar e resolver ou reabrir uma thread. |
| Diagramas | `kb_list_diagrams`, `kb_read_diagram`, `kb_create_diagram`, `kb_draw_diagram`, `kb_edit_diagram`, `kb_duplicate_diagram`, `kb_diagram_history`, `kb_restore_diagram` | Ler, desenhar, modificar e restaurar diagramas. |
| Cofre | `kb_list_credentials` | Consultar os nomes, os hosts e os usuários das credenciais. Nunca os seus valores. |
| Compartilhar | `kb_share_page` | Alterar com quais organizações uma página é compartilhada. |
| Validação | `kb_mark_ready_for_review` | Marcar uma página como pronta para revisão. |
| Ícones | `kb_list_icons` | Consultar os ícones próprios da organização. |

A API REST oferece as mesmas operações. A especificação OpenAPI descreve todas elas.

## Regras para os agentes

As mesmas regras se aplicam a qualquer agente, seja do Flexxible Assist ou seu:

* **Nunca obtêm o valor de uma credencial.** Veem nomes, tipos, hosts e usuários, e podem vincular uma credencial em uma página.
* **Não podem escrever segredos.** Toda escrita passa por um detector de segredos. Se ela adicionar uma senha, um token ou uma chave, é rejeitada com a indicação de usar o Cofre.
* **Editam, não reescrevem.** As alterações são enviadas como substituições exatas de texto sobre a página tal como ela está, de modo que uma pessoa que esteja editando a mesma página preserve o seu trabalho. Se alguém tiver alterado o mesmo texto nesse meio-tempo, a escrita é rejeitada e o agente deve ler a página novamente.
* **Podem desfazer os seus próprios erros.** Um agente não pode desfazer a alteração que criou uma página, porque isso equivaleria a excluí-la.
* **Somente pessoas validam.** Um agente pode marcar uma página como pronta para revisão, mas não validá-la.
* **Acessam somente a sua organização.** Uma chave dá acesso às páginas da sua organização e às que outras organizações compartilham com ela, que são somente leitura.

## Gerenciar agentes e chaves

Abra um agente em **Configurações** → **Agentes** para ver as suas chaves, com a data de criação e de último uso de cada uma.

* **Revogar** invalida uma chave na hora.
* **Excluir agente** invalida todas as suas chaves. As suas edições permanecem no Histórico.
* **Atividade** mostra cada chamada do agente e com qual chave ela foi feita. Consulte [Atividade dos agentes](https://docs.flexxible.com/pt-BR/features/flexxible-kb/assist-agents.md#actividad-de-los-agentes).

## Próximos passos

* [Agentes do Flexxible Assist](https://docs.flexxible.com/pt-BR/features/flexxible-kb/assist-agents.md)
* [Cofre](https://docs.flexxible.com/pt-BR/features/flexxible-kb/vault.md)
* [Servidor MCP da Flexxible](https://docs.flexxible.com/pt-BR/features/integrations/mcp.md)
