Infino

Infino — recuperação por palavra-chave, vetorial, híbrida e SQL sobre dados em armazenamento de objetos, para agentes de IA.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Infino

Um servidor MCP para Infino — ele permite que um agente de IA execute consultas por palavra-chave, semânticas, híbridas e SQL sobre seus dados em armazenamento de objetos — a camada de recuperação para RAG, memória persistente de agentes e busca em seus próprios arquivos — a partir de qualquer cliente compatível com MCP (Claude Code, Claude Desktop, Cursor, VS Code e outros). Publicado no npm como @infino-ai/mcp-server e listado no Registro oficial de MCP como io.github.infino-ai/mcp-server (o que propaga para catálogos como Smithery, Glama e PulseMCP).

Embeddings locais, sem chave. A busca semântica incorpora consultas com um modelo local — nada sai da máquina para a incorporação.
O agente é dono dos dados. Todas as ferramentas, incluindo as de escrita, estão sempre disponíveis. No Infino Cloud, as capacidades da chave de API decidem o que uma conexão pode fazer; toda ferramenta carrega anotações MCP para que seu cliente possa perguntar antes de uma chamada destrutiva.
Local ou hospedado. Aponte para um caminho local, seu próprio bucket (S3, Azure ou qualquer armazenamento compatível com S3) ou um endpoint hospedado do Infino Cloud com chave de API.
O índice é um arquivo Parquet válido. Uma tabela armazena os dados e seus índices de busca em Parquet simples no armazenamento — abra o mesmo arquivo com DuckDB ou pyarrow. Sem exportação, sem aprisionamento.

Conteúdo

Requisitos
Início rápido
Plugin do Claude Code (instalação em uma etapa)
Configuração do cliente
Configuração
- Variáveis de ambiente
- Backends de armazenamento
Ferramentas
Segurança e tratamento de dados
Como funciona a recuperação
Solução de problemas
Desenvolvimento local
Licença

Requisitos

Node.js ≥ 20 (o servidor roda como um processo Node via stdio).
Um cliente compatível com MCP (Claude Code, Claude Desktop, Cursor, VS Code, …).
Dados acessíveis pelo Infino — um diretório local, um bucket com credenciais disponíveis no ambiente ou um endpoint hospedado do Infino Cloud com chave de API (veja Backends de armazenamento).
Na primeira execução, o servidor baixa o modelo de embedding local (~90 MB) uma vez e o armazena em cache; execuções subsequentes são offline para incorporação.

Início rápido

O servidor é iniciado pelo seu cliente MCP via stdio — você não o executa diretamente no uso normal. Toda configuração de cliente segue o mesmo formato: comando npx -y @infino-ai/mcp-server, com configuração fornecida por variáveis de ambiente. Defina INFINO_MCP_URI para os dados que você quer servir — um caminho local ou um URI de bucket. Se for omitido, o servidor usa um diretório durável por usuário (~/.infino/mcp) para que os dados persistam entre reinicializações; aponte INFINO_MCP_URI para seu próprio caminho ou bucket para servir dados existentes.

{
  "command": "npx",
  "args": ["-y", "@infino-ai/mcp-server"],
  "env": {
    "INFINO_MCP_URI": "/Users/me/.infino/memory"
  }
}

Para servir um banco de dados hospedado no Infino Cloud em vez disso, aponte INFINO_MCP_URI para o endpoint https://<host>/<database> e forneça sua chave de API. Todo o resto é idêntico:

{
  "command": "npx",
  "args": ["-y", "@infino-ai/mcp-server"],
  "env": {
    "INFINO_MCP_URI": "https://api.platform.infino.ws/my-database",
    "INFINO_API_KEY": "inf_…"
  }
}

As seções abaixo mostram o local exato onde cada cliente espera este bloco.

Plugin do Claude Code (instalação em uma etapa)

Para Claude Code, este repositório também é um marketplace de plugins. Instalar o plugin conecta o servidor MCP mais uma habilidade de como usar e um comando /infino-search em uma única etapa — sem precisar editar JSON. Dentro do Claude Code:

/plugin marketplace add infino-ai/infino-mcp
/plugin install infino@infino-ai

Ao ativar, você será solicitado a fornecer seu URI de dados do Infino (INFINO_MCP_URI) e, para o Infino Cloud, sua chave de API. É isso: as ferramentas infino_*, a habilidade using-infino e /infino-search <query> estarão então disponíveis. (Outros clientes: use as configurações de Configuração do cliente abaixo.)

Configuração do cliente

Claude Code

Adicione o servidor com a CLI. Use --scope user para disponibilizá-lo em todos os projetos, ou --scope project para comprometê-lo no repositório (grava um .mcp.json compartilhado); o escopo padrão é local (apenas este projeto).

claude mcp add infino \
  --scope user \
  -e INFINO_MCP_URI=/Users/me/.infino/memory \
  -- npx -y @infino-ai/mcp-server

Adicione mais opções com flags -e repetidas, ex.: -e INFINO_MCP_VALIDATE=true. Verifique com:

claude mcp list
claude mcp get infino

Claude Desktop

Edite o arquivo de configuração (crie-o se não existir) e reinicie completamente o Claude Desktop.

SO	Caminho
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "infino": {
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

Cursor

Adicione o servidor em ~/.cursor/mcp.json (disponível em todos os projetos) ou <project>/.cursor/mcp.json (apenas neste projeto) e recarregue. O formato corresponde ao do Claude Desktop:

{
  "mcpServers": {
    "infino": {
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

VS Code

O VS Code (1.102+) lê servidores MCP de .vscode/mcp.json no workspace (ou do seu mcp.json de usuário via paleta de comandos → MCP: Open User Configuration). Observe que a chave de nível superior é servers e cada entrada declara "type": "stdio":

{
  "servers": {
    "infino": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@infino-ai/mcp-server"],
      "env": {
        "INFINO_MCP_URI": "/Users/me/.infino/memory"
      }
    }
  }
}

Outros clientes MCP

Qualquer cliente que fale MCP via stdio funciona. Configure-o para iniciar:

command: npx
args:    -y @infino-ai/mcp-server
env:     INFINO_MCP_URI=<path-or-bucket-uri>   (plus any options below)

Os logs são gravados em stderr para que nunca corrompam o fluxo JSON-RPC no stdout — aponte a captura de logs do seu cliente para lá ao depurar.

Configuração

Toda a configuração é feita por variáveis de ambiente — não há arquivos de configuração nem flags de linha de comando para gerenciar.

Variáveis de ambiente

Variável	Obrigatória	Padrão	Descrição
`INFINO_MCP_URI`	Não	`~/.infino/mcp` (persistente)	Dados a servir: um caminho local (`/Users/me/.infino/memory`), um URI de bucket (`s3://…`, `az://…`) ou um endpoint hospedado (`https://<host>/<database>`, Infino Cloud). Se não definido, um diretório durável por usuário (`~/.infino/mcp`) é usado para que os dados persistam entre reinicializações; ele recorre a um catálogo efêmero em processo (`memory://`) apenas se esse diretório não puder ser criado.
`INFINO_API_KEY`	Com um URI hospedado	—	Chave de API (`inf_…`) para um endpoint `https://` hospedado. Obrigatória quando `INFINO_MCP_URI` é um URI `https://`; ignorada para conexões locais e de armazenamento de objetos.
`INFINO_MCP_EMBED_PROVIDER`	Não	`local`	Provedor de embeddings: `local` (Hugging Face transformers.js, sem chave, nada sai da máquina) ou `openai` (qualquer endpoint `/embeddings` compatível com OpenAI — OpenAI, a superfície `/openai/v1` do Azure OpenAI ou um servidor compatível). Inferido como `openai` quando `INFINO_MCP_EMBED_BASE_URL` está definido.
`INFINO_MCP_EMBED_BASE_URL`	Com `openai`	—	URL base da API de embeddings compatível com OpenAI, ex.: `https://api.openai.com/v1` ou `https://<resource>.openai.azure.com/openai/v1`. O servidor faz POST para `<base>/embeddings`.
`INFINO_MCP_EMBED_API_KEY`	Não	—	Chave de API para o provedor `openai`. Enviada tanto como `Authorization: Bearer` quanto como `api-key`, então um único valor funciona para OpenAI e Azure OpenAI. Omita para chamar um endpoint não autenticado ou com identidade ambiente.
`INFINO_MCP_EMBED_MODEL`	Não	`Xenova/all-MiniLM-L6-v2` (local) · `text-embedding-3-small` (openai)	O modelo de embeddings. Para `local`, um modelo de extração de características do Hugging Face; para `openai`, o nome do modelo/implantação. Deve corresponder ao modelo que produziu os vetores armazenados da tabela — e, portanto, à dimensão do índice vetorial (ex.: `text-embedding-3-small` tem 1536 dimensões; o modelo local padrão tem 384 dimensões).
`INFINO_MCP_VALIDATE`	Não	desligado	Quando definido (`1`/`true`/`yes`), testa o armazenamento de objetos na inicialização para que credenciais ruins ou um bucket inacessível falhem nesse momento, em vez de na primeira busca.

As credenciais da nuvem são lidas das variáveis de ambiente padrão do provedor — o servidor as mapeia para a configuração do armazenamento e não introduz variáveis de credenciais próprias. Omita-as completamente para usar identidade de nuvem ambiente (uma função de instância IAM ou identidade gerenciada do Azure).

Servindo um catálogo incorporado com OpenAI / Azure OpenAI. Se suas tabelas foram vetorizadas com um modelo de embeddings hospedado em vez do padrão local, aponte o servidor para esse mesmo modelo para que os vetores de consulta e de documento se alinhem:

"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "INFINO_MCP_EMBED_PROVIDER": "openai",
  "INFINO_MCP_EMBED_BASE_URL": "https://my-resource.openai.azure.com/openai/v1",
  "INFINO_MCP_EMBED_API_KEY": "…",
  "INFINO_MCP_EMBED_MODEL": "text-embedding-3-small"
}

O modelo deve corresponder ao que produziu os vetores armazenados — uma incompatibilidade gera similaridade sem sentido ou um erro de dimensão. A busca por palavra-chave e SQL não é afetada pelo incorporador.

Backend	Credenciais
AWS S3	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (+ `AWS_SESSION_TOKEN`, `AWS_REGION` se usados)
Compatível com S3 (R2/MinIO/B2)	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_ENDPOINT_URL`
Azure Blob	`AZURE_STORAGE_ACCOUNT`, `AZURE_STORAGE_KEY`
Infino Cloud (hospedado)	`INFINO_API_KEY` — nenhuma credencial de armazenamento de objetos necessária (a plataforma é dona do armazenamento)

Backends de armazenamento

// Local directory
"env": { "INFINO_MCP_URI": "/Users/me/.infino/memory" }

// AWS S3 — ambient AWS_* credentials, default endpoint
"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "AWS_ACCESS_KEY_ID": "…",
  "AWS_SECRET_ACCESS_KEY": "…"
}

// S3-compatible (Cloudflare R2 / MinIO / Backblaze B2) — custom endpoint
"env": {
  "INFINO_MCP_URI": "s3://my-bucket/infino",
  "AWS_ENDPOINT_URL": "https://<account>.r2.cloudflarestorage.com",
  "AWS_ACCESS_KEY_ID": "…",
  "AWS_SECRET_ACCESS_KEY": "…"
}

// Azure Blob
"env": {
  "INFINO_MCP_URI": "az://my-container/infino",
  "AZURE_STORAGE_ACCOUNT": "…",
  "AZURE_STORAGE_KEY": "…"
}

// Infino Cloud (hosted) — the database is the last path segment
"env": {
  "INFINO_MCP_URI": "https://api.platform.infino.ws/my-database",
  "INFINO_API_KEY": "inf_…"
}

Em uma conexão hospedada, as ferramentas de busca, SQL e escrita se comportam exatamente como localmente — a única diferença é onde os dados vivem. Compactação e coleta de lixo são tratadas no lado do servidor, portanto não são expostas como operações do cliente. Observe que a busca semântica e híbrida ainda incorporam consultas localmente neste servidor, então INFINO_MCP_EMBED_MODEL deve corresponder ao modelo que produziu os vetores armazenados da tabela hospedada (veja a nota sobre OpenAI / Azure OpenAI acima) — isso importa especialmente quando outra pessoa ingeriu os dados.

Ferramentas

Ferramenta	Argumentos	O que faz
`infino_semantic_search`	`table`, `query`, `k`, `column?`, `vectorColumn?`, `columns?`, `filter?`	Encontra passagens por significado — incorpora a consulta com um modelo local (sem chave) e classifica por similaridade vetorial. Lida com paráfrases e sinônimos. `score` é uma distância (quanto menor, mais próximo). O `filter` opcional (`{column, query, mode?}`) restringe a classificação às linhas cuja coluna de palavras-chave corresponde primeiro (um pré-filtro pushdown). O `columns` opcional escolhe quais campos cada resultado retorna (ex.: um caminho + intervalo de linhas para citar); o padrão é a coluna de texto, com `_id` e `score` sempre incluídos.
`infino_keyword_search`	`table`, `query`, `k`, `column?`, `mode?`, `stats?`, `columns?`	Pesquisa de texto completo BM25 — para termos exatos, identificadores, códigos de erro, nomes de produtos. `score` é uma relevância (quanto maior, melhor). `mode` é `or` (padrão) ou `and`; `stats` é `per_superfile` (padrão) ou `global` para um único idf por tabela.
`infino_hybrid_search`	`table`, `query`, `k`, `column?`, `vectorColumn?`, `mode?`, `columns?`	Pesquisa combinada de palavras-chave + semântica em uma única passagem de classificação — BM25 sobre a coluna de texto combinado com similaridade vetorial, de modo que linhas que correspondem aos termos literais e ao significado ficam no topo. `score` é a classificação combinada (quanto maior, melhor).
`infino_token_match`	`table`, `query`, `column?`, `mode?`, `limit?`	Filtro de palavras-chave sem classificação — o conjunto de linhas cuja coluna de texto contém o(s) token(s). Use quando precisar das correspondências, não de uma ordem de relevância.
`infino_exact_match`	`table`, `value`, `column?`, `limit?`	Filtro de igualdade exata sem classificação sobre uma coluna indexada (tag, status, string de id).
`infino_count`	`table`, `query`, `column?`, `mode?`	Conta quantas linhas correspondem a uma consulta de palavras-chave, sem buscá-las — uma contagem rápida sobre a coluna de texto. Para as linhas correspondentes, use `infino_keyword_search` ou `infino_token_match`.
`infino_sql`	`query`, `embed?`	SQL para contagens, filtros, junções, agregações. As funções de tabela de pesquisa do mecanismo são chamáveis dentro dele; um espaço reservado `{{name}}` é preenchido com o vetor de `embed[name]`. Qualquer instrução única, incluindo DDL/DML.
`infino_list_tables`	—	Lista as tabelas no catálogo conectado.
`infino_describe_table`	`table`	Nomes e tipos de colunas de uma tabela.
`infino_create_database`	—	Provisiona o banco de dados que a conexão nomeia (Infino Cloud); um no-op de sucesso localmente. Idempotente.
`infino_create_table`	`table`, `columns`, `fts?`, `vector?`	Cria uma tabela a partir de um descritor `{column: type}`. Índices de texto completo em `fts` (padrão: toda coluna `large_utf8`). `vector: true` adiciona uma coluna `embedding` dimensionada para o incorporador do servidor, com um índice de cosseno.
`infino_drop_table`	`table`, `purge?`	Remove uma tabela e, por padrão, exclui seus objetos de armazenamento; `purge: false` apenas desregistra o nome.
`infino_add_documents`	`table`, `documents`	Acrescenta linhas (uma chamada = um commit). Linhas sem vetor são incorporadas a partir da coluna de texto, todas em um único lote; o resultado relata `appended` e `embedded`. Uma chave que não é uma coluna é um erro.
`infino_update_documents`	`table`, `predicate`, `documents`	Substitui as linhas que correspondem a um predicado SQL por novos documentos, 1:1 (vetores ausentes são incorporados). Somente armazenamento durável.
`infino_delete_documents`	`table`, `predicate`	Exclui as linhas que correspondem a um predicado SQL. Somente armazenamento durável.

Os resultados de pesquisa retornam valores completos de coluna — o argumento columns é uma projeção passada diretamente ao mecanismo (incorporado ou hospedado), de modo que qualquer coluna da tabela pode voltar com cada resultado: ["id"] para resultados compactos em um k grande, ["id", "text"] para o texto completo junto com um id para citar, colunas de metadados para filtragem. O padrão é a coluna de texto, com _id e score sempre incluídos, e nada é truncado; para manter os resultados pequenos, projete menos colunas ou peça um k menor. Cada resposta de pesquisa também carrega score_kind, indicando se seu score é uma distância (semântica: quanto menor, mais próximo) ou uma relevância (palavras-chave e híbrida: quanto maior, melhor).

Para recuperação simples, prefira as ferramentas de pesquisa dedicadas, que incorporam e projetam para você. infino_sql é para filtros, junções e agregações, inclusive sobre os resultados de uma função de tabela de pesquisa, de modo que uma única consulta pode classificar e agregar ao mesmo tempo.

Gravando dados

O caminho de gravação que um agente segue, cada etapa uma chamada de ferramenta e um commit:

infino_create_database se um banco de dados hospedado responder 404.
infino_create_table com uma coluna de chave utf8, colunas de texto large_utf8 e vector: true para pesquisa semântica. O servidor dimensiona a coluna de vetor para seu incorporador; o agente nunca digita uma dimensão. Guarde o resultado: seu campo indexes é o único registro de quais colunas estão indexadas.
infino_add_documents, dezenas de linhas por chamada, sempre incluindo a chave. Vetores ausentes são incorporados em um único lote.
Para substituir linhas, infino_delete_documents por predicado de chave e depois adicione novamente. Para remover linhas, verifique o predicado com infino_count primeiro.

Uma chamada de ferramenta carrega dezenas de documentos. Para um corpus inteiro, use a CLI infino (infino ingest aceita Parquet ou NDJSON contra o mesmo URI) ou um SDK. A CLI é traga-seus-próprios-vetores como o mecanismo, então inclua a coluna embedding nas linhas ou carregue texto e pesquise por palavras-chave.

Não há porta de gravação no lado do servidor, e a variável aposentada INFINO_MCP_ENABLE_WRITES é ignorada (o servidor avisa no stderr se ela estiver definida). No Infino Cloud, as capacidades da chave de API limitam o que a conexão pode fazer: uma chave com escopo somente leitura tem toda gravação recusada, e o resultado da ferramenta diz para emitir uma com capacidade de gravação. Localmente, aponte o servidor apenas para dados que o agente pode alterar.

Segurança e tratamento de dados

Este servidor roda localmente, ao lado do cliente, e mantém dados e credenciais na máquina do usuário.

Execução local, sem listener de entrada. Ele roda como um subprocesso do seu cliente MCP via stdio e não abre nenhum listener de rede. No modo local/bucket padrão, não contata nenhum serviço remoto. Quando INFINO_MCP_URI é um endpoint https:// hospedado, ele faz chamadas TLS de saída para esse endpoint para atender pesquisas, SQL e (se habilitado) gravações — portanto, os dados nessas requisições chegam ao serviço hospedado que você configurou, e nada mais.
Nenhum dado enviado para incorporação, por padrão. Com o provedor padrão, a incorporação de consultas e documentos usa um modelo local, então o texto nunca é enviado a uma API de incorporação de terceiros e não há chave de API de incorporação para provisionar ou vazar. No modo hospedado, apenas o vetor resultante, não o texto, chega ao endpoint do Infino Cloud. Se você configurar o provedor compatível com OpenAI, o texto sendo incorporado é enviado ao endpoint que você nomear.
Credenciais permanecem no ambiente. Credenciais de armazenamento (AWS_*/AZURE_*) e a chave de API hospedada (INFINO_API_KEY) são lidas de variáveis de ambiente e usadas apenas para alcançar o armazenamento ou endpoint que você configurou. Elas nunca são registradas em log nem retornadas na saída das ferramentas.
Quem pode gravar é decidido fora do servidor. O conjunto completo de ferramentas, incluindo gravações, está sempre disponível ao agente. No Infino Cloud, as capacidades da chave de API limitam o que a conexão pode fazer (uma chave com escopo somente leitura tem toda gravação recusada). Localmente, aponte o servidor apenas para dados que o agente pode alterar. Cada ferramenta carrega anotações MCP (readOnlyHint, destructiveHint) para que seu cliente possa pedir confirmação em seus próprios termos.
Menor privilégio. Aponte INFINO_MCP_URI para o conjunto de dados mais restrito que a tarefa precisar e forneça credenciais de armazenamento com escopo para esse bucket/prefixo.

Como a recuperação funciona

A pesquisa semântica incorpora localmente com Hugging Face transformers.js (all-MiniLM-L6-v2, 384 dimensões por padrão; substitua com INFINO_MCP_EMBED_MODEL). O servidor incorpora tanto os documentos que ingere (via infino_add_documents) quanto suas consultas com o mesmo modelo, para que se alinhem no mesmo espaço vetorial.

Se você alterar INFINO_MCP_EMBED_MODEL, o índice vetorial da tabela deve corresponder à dimensão do novo modelo — incorporações produzidas por modelos diferentes não são comparáveis, e uma incompatibilidade de dimensão falhará no momento da pesquisa.

Solução de problemas

Sintoma	Causa provável / correção
O cliente não mostra ferramentas do Infino	O servidor não iniciou — verifique os logs MCP do cliente (stderr). Confirme que `npx` está em `PATH` e que `INFINO_MCP_URI` está definido. Reinicie completamente o cliente após editar a configuração.
`INFINO_MCP_URI is required`	A variável de ambiente não está alcançando o subprocesso. Em clientes GUI, o ambiente deve estar dentro do bloco `env` do servidor (o processo não herdará seu shell).
Uma gravação diz que a chave "foi rejeitada ou não tem capacidade de gravação"	No Infino Cloud, a chave de API tem escopo somente leitura (HTTP 403) ou está errada. Emita uma chave com capacidade de gravação e reinicie o servidor com ela.
Uma gravação diz "outro escritor venceu a corrida de commit"	Dois escritores atingiram a mesma tabela ao mesmo tempo e esta chamada não foi aplicada. Reenvie-a.
Primeira consulta lenta	Download único do modelo de incorporação (~90 MB). Execuções subsequentes usam o cache.
Erro de autenticação contra um URI `https://` hospedado	`INFINO_API_KEY` está ausente, errado ou sem acesso a esse banco de dados. Confirme a chave (`inf_…`) e que o último segmento de caminho do URI é um banco de dados que você pode alcançar.
Erros de dimensão/vetor na pesquisa semântica	O índice vetorial da tabela não corresponde à dimensão do modelo de incorporação. Reingira ou defina `INFINO_MCP_EMBED_MODEL` para o modelo com o qual o índice foi construído.

Desenvolvimento local

O servidor depende do binding Node @infino-ai/infino publicado, que é resolvido do npm público como qualquer outra dependência.

npm install
npm run build
INFINO_MCP_URI=/path/to/data node dist/index.js   # runs on stdio

Aponte um cliente para node /absolute/path/dist/index.js via stdio para testar uma build local, ou use o MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Licença

Apache-2.0