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

# Guias

> Como o CaktoMCP lê esta documentação em tempo real, via cakto_search_docs e cakto_get_guide.

O CaktoMCP **lê esta documentação diretamente**, em tempo de execução. Não
existe uma segunda versão dos textos guardada dentro do servidor: quando a IA
responde uma dúvida de conceito, ela está lendo a mesma página que você lê
aqui, na versão que está publicada agora.

<Note>
  Isso mudou. Até setembro de 2026 o servidor servia dez guias curtos,
  mantidos separadamente desta documentação. Eram uma segunda cópia, e cópias
  divergem — houve pelo menos um caso em que o guia afirmava o oposto do que
  esta documentação (corretamente) dizia sobre idempotência. A cópia foi
  removida. **Esta página é a fonte; o MCP é um leitor.**
</Note>

## As duas ferramentas

### `cakto_search_docs`

O catálogo. Busca por título e descrição em todas as páginas publicadas —
conceitos, guias de início, SDK do checkout, referência de API e as próprias
páginas do CaktoMCP.

| Parâmetro | Tipo    | Obrigatório              | Descrição                                                                        |
| --------- | ------- | ------------------------ | -------------------------------------------------------------------------------- |
| `query`   | string  | Não                      | Assunto procurado. **Sem valor, devolve o catálogo inteiro**, agrupado por seção |
| `limit`   | integer | Não (default 8, máx. 25) | Quantos resultados retornar                                                      |

Retorna, para cada página, o `slug`, o título e a descrição. O `slug` é o que
se passa para `cakto_get_guide`.

**Exemplo:**

```
cakto_search_docs(query: "não gerar cobrança duplicada")
```

### `cakto_get_guide`

Lê uma página inteira, pelo slug.

| Parâmetro | Tipo   | Obrigatório | Descrição                                                                     |
| --------- | ------ | ----------- | ----------------------------------------------------------------------------- |
| `topic`   | string | Sim         | O slug da página — ex.: `conceitos/idempotencia`, `authentication`, `sdk/3ds` |

Retorna o texto da página, precedido de um cabeçalho curto com a URL de
origem e o instante da leitura — para a IA poder citar a fonte e você poder
conferir.

**Exemplo:**

```
cakto_get_guide(topic: "conceitos/idempotencia")
```

<Tip>
  Não é preciso acertar o slug de primeira. Um slug que não existe volta com
  as páginas mais parecidas como sugestão, e os dez tópicos do formato antigo
  (`idempotencia`, `webhooks`, `autenticacao`, `checkout-builder`,
  `primeiros-passos`, `erros`, `paginacao`, `ambientes`,
  `fluxo-de-pagamento`) continuam sendo aceitos como apelido do slug
  correspondente.
</Tip>

## O que isso significa na prática

* **A resposta da IA acompanha a documentação.** Uma correção publicada aqui
  chega ao MCP em poucos minutos, sem nova versão do servidor.
* **Não há divergência possível entre "o que a doc diz" e "o que a IA diz".**
  É o mesmo texto.
* **Página nova aparece sozinha.** O catálogo é lido a cada consulta; não há
  lista fixa de assuntos.

<Warning>
  Para o contrato de um endpoint — parâmetros, corpo, respostas —, prefira
  `cakto_get_endpoint`. Ele lê o contrato da API de forma estruturada, é mais
  preciso e muito mais econômico que a página de referência correspondente.
  Use `cakto_get_guide` para conceito, não para assinatura de endpoint.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ferramentas de Descoberta" icon="magnifying-glass" href="/mcp/ferramentas-de-descoberta">
    Buscar endpoints e ler contratos completos
  </Card>

  <Card title="Ferramentas de Execução" icon="bolt" href="/mcp/ferramentas-de-execucao">
    Como a execução real funciona
  </Card>
</CardGroup>