AIVAX

Esta página foi traduzida automaticamente do inglês e pode estar desatualizada. Leia o original

Coleções e RAG MCP

O MCP de Coleções expõe uma ou mais coleções AIVAX RAG como ferramentas para clientes MCP compatíveis. Use-o quando um modelo externo, agente, IDE ou assistente de desktop precisar decidir quando buscar em uma base de conhecimento AIVAX.

Para um cliente de chat AIVAX típico, geralmente é mais simples anexar a coleção diretamente a um AI Gateway e deixar que o pipeline RAG do gateway recupere os documentos automaticamente.

Para informações sobre como criar coleções, preparar documentos e melhorar a qualidade da recuperação, consulte Coleções, Documentos e Busca Semântica.

Endpoint #

TEXT
https://inference.aivax.net/v1/mcp/collections

Cabeçalhos #

CabeçalhoDescriçãoPadrão
AuthorizationToken Bearer da sua chave de API.Obrigatório
X-Mcp-Collection-IdUm ou mais IDs de coleção. Use vírgulas para múltiplas coleções.Obrigatório
X-Mcp-Collection-NameNome da coleção usado para gerar nomes de ferramentas.collection
X-Mcp-RerankerSeleciona o classificador usado para ordenar os resultados da busca. Use um @provider/name, lexical, rrf, smart ou none canônicos.@aivax/reflex-v1
X-Mcp-Top-KNúmero máximo de resultados a retornar.5
X-Mcp-Min-ScorePontuação mínima de relevância maior que 0 e até 1,0.0.4
X-Mcp-Use-ReferencesDefina como none para habilitar referências nos resultados da busca; omita o cabeçalho para desabilitá-las.desativado
X-Mcp-Allow-WriteUse yes para expor ferramentas de gravação e exclusão de documentos.desativado
X-Mcp-Naming-ConventionControla como as ferramentas geradas são nomeadas. Use default ou agent.default
X-Mcp-Enabled-ToolsLista de permissão separada por vírgulas dos tipos de ferramentas a expor: search, browse, get, write, delete. Consulte Selecionar quais ferramentas são expostas.todas as ferramentas disponíveis

Exemplo de configuração #

Visual Studio Code:

JSON
{
  "servers": {
    "my-rag-collection-mcp": {
      "type": "http",
      "url": "https://inference.aivax.net/v1/mcp/collections",
      "headers": {
        "Authorization": "Bearer <AIVAX_API_KEY>",
        "X-Mcp-Collection-Id": "<COLLECTION_ID>",
        "X-Mcp-Collection-Name": "my_collection",
        "X-Mcp-Top-K": "5",
        "X-Mcp-Min-Score": "0.4",
        // Habilita referências nos resultados da busca.
        "X-Mcp-Use-References": "none"
      }
    }
  }
}

Ferramentas geradas #

O servidor gera até cinco ferramentas por configuração: search (busca), browse (navegar), get document (obter documento) e, quando as gravações são permitidas, write (gravar) e delete (excluir). Os nomes das ferramentas são construídos a partir de X-Mcp-Collection-Name e da convenção de nomenclatura.

Ferramenta de Busca #

Com a convenção de nomenclatura padrão, a ferramenta de leitura é nomeada:

TEXT
{collection_name}_search

Ela aceita:

  • search_terms (string[]): um ou mais termos de busca.
  • filter (string, opcional): um filtro de documento aplicado antes da busca semântica, como tags has "faq" and updatedAt >= now-30d.

A ferramenta de leitura MCP aceita no máximo 10 termos de busca e 500 caracteres totais por chamada.

Ferramenta de Navegação #

A ferramenta de navegação lista documentos indexados em uma ordem fixa, sem busca semântica. Use-a quando o modelo precisar ver o que uma coleção contém, percorrer página por página todos os documentos ou ler um documento pelo seu nome exato. Com a convenção de nomenclatura padrão, ela é nomeada:

TEXT
{collection_name}_browse_documents

Com a convenção de nomenclatura agent, ela é nomeada {collection_name}_list. Ela aceita:

  • filter (string, opcional): um filtro de documento, como name = "setup.md", reference = "manual-v2" ou tags has "faq".
  • sort (string, opcional): createdAt, updatedAt, indexedAt ou name. O padrão é createdAt.
  • descending (boolean, opcional): lista os mais recentes primeiro, ou de Z a A ao classificar por nome. O padrão é false.
  • include_content (boolean, opcional): adiciona o conteúdo e metadados de cada documento. O padrão é false, então a ferramenta retorna apenas nomes, tags, referências e datas. Para ler um único documento, prefira a ferramenta de obter documento.
  • limit (number, opcional): documentos por página, de 1 a 50. O padrão é 20.
  • cursor (string, opcional): o next_cursor retornado pela chamada anterior. Envie-o com os mesmos valores de filter, sort e descending para ler a próxima página. Os cursores não expiram.

A ferramenta de navegação não incorpora nem reclassifica nada, portanto, não tem custo de busca, mas cada chamada conta para o limite de taxa de busca do seu plano. Os documentos aparecem nela apenas após serem indexados.

Ferramenta de Obter Documento #

A ferramenta de obter documento lê um único documento pelo seu nome exato, como um nome retornado pela ferramenta de navegação. Com a convenção de nomenclatura padrão, ela é nomeada:

TEXT
{collection_name}_get_document

Com a convenção de nomenclatura agent, ela é nomeada {collection_name}_get. Ela aceita:

  • name (string): o nome exato do documento.
  • start_line e end_line (number, opcionais): um intervalo de linhas inclusivo baseado em 1. Sem eles, o documento inteiro é retornado.

Ela retorna o nome, tags, referência, metadados, datas, se o documento já está indexado e o intervalo de linhas selecionado, seguido pelo conteúdo.

  • Uma única chamada retorna no máximo 100.000 caracteres. Leia documentos mais longos em partes usando start_line e end_line.
  • Documentos que ainda estão aguardando indexação também podem ser lidos.
  • Quando várias coleções estão configuradas, a primeira coleção em X-Mcp-Collection-Id que possui um documento com esse nome é usada.
  • Como a ferramenta de navegação, ela não tem custo de busca e conta para o limite de taxa de busca.

Ferramentas de Gravação e Exclusão #

Quando X-Mcp-Allow-Write está desativado, apenas as ferramentas de busca, navegação e obter documento são expostas. Este é o modo recomendado para assistentes que precisam apenas ler uma base de conhecimento.

Quando X-Mcp-Allow-Write: yes é enviado, o servidor também expõe ferramentas de criação/atualização e exclusão de documentos. Habilite isso apenas para clientes confiáveis, pois um modelo com acesso de gravação pode alterar o conteúdo da coleção.

Para uma configuração de agente de codificação com uma coleção de runbook somente leitura e uma coleção de notas com gravação habilitada, consulte Claude Code memory MCP.

Selecionar quais ferramentas são expostas #

Use o cabeçalho opcional X-Mcp-Enabled-Tools para expor apenas algumas das ferramentas geradas. Forneça uma lista de permissão separada por vírgulas dos tipos de ferramentas, não os nomes das ferramentas geradas, para que o mesmo valor funcione com qualquer nome de coleção e convenção de nomenclatura:

  • search: a ferramenta de leitura.
  • browse: a ferramenta de navegação.
  • get: a ferramenta de obter documento.
  • write: a ferramenta de criação/atualização de documento.
  • delete: a ferramenta de exclusão de documento.

Por exemplo, para permitir que um cliente adicione documentos e faça buscas sem poder excluí-los:

TEXT
X-Mcp-Allow-Write: yes
X-Mcp-Enabled-Tools: search, write

Para permitir que um cliente liste e leia documentos sem busca semântica:

TEXT
X-Mcp-Enabled-Tools: browse, get

Para expor apenas a ferramenta de gravação, para um agente de ingestão que não deve ler a coleção:

TEXT
X-Mcp-Allow-Write: yes
X-Mcp-Enabled-Tools: write

A lista de permissão apenas restringe o conjunto de ferramentas. write e delete ainda exigem X-Mcp-Allow-Write: yes; sem ele, eles não são expostos mesmo quando listados. Sem X-Mcp-Enabled-Tools, o servidor expõe todas as ferramentas permitidas pelos outros cabeçalhos. Os valores não diferenciam maiúsculas de minúsculas, espaços em torno das vírgulas são ignorados e valores desconhecidos são ignorados.

Digite para pesquisar na documentação.