Infino

Infino: recuperación por palabra clave, vectorial, híbrida y SQL sobre datos en almacenamiento de objetos, para agentes de IA.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Infino

Un servidor MCP para Infino — permite que un agente de IA ejecute recuperación por palabras clave, semántica, híbrida y SQL sobre tus datos en almacenamiento de objetos — la capa de recuperación para RAG, memoria persistente del agente y búsqueda sobre tus propios archivos — desde cualquier cliente compatible con MCP (Claude Code, Claude Desktop, Cursor, VS Code y otros). Publicado en npm como @infino-ai/mcp-server y listado en el Registro oficial de MCP como io.github.infino-ai/mcp-server (que se propaga a catálogos como Smithery, Glama y PulseMCP).

Embeddings locales, sin clave. La búsqueda semántica incorpora consultas con un modelo local — nada sale de la máquina para la incorporación.
El agente es dueño de los datos. Cada herramienta, incluidas las de escritura, está siempre disponible. En Infino Cloud, las capacidades de la clave API deciden qué puede hacer una conexión; cada herramienta lleva anotaciones MCP para que tu cliente pueda preguntar antes de una llamada destructiva.
Local o alojado. Apúntalo a una ruta local, a tu propio bucket (S3, Azure o cualquier almacén compatible con S3) o a un endpoint alojado de Infino Cloud con una clave API.
El índice es un archivo Parquet válido. Una tabla almacena los datos y sus índices de búsqueda en Parquet plano en el almacenamiento — abre el mismo archivo con DuckDB o pyarrow. Sin exportación, sin bloqueo.

Contenido

Requisitos
Inicio rápido
Plugin de Claude Code (instalación en un paso)
Configuración del cliente
Configuración
- Variables de entorno
- Backends de almacenamiento
Herramientas
Seguridad y manejo de datos
Cómo funciona la recuperación
Solución de problemas
Desarrollo local
Licencia

Requisitos

Node.js ≥ 20 (el servidor se ejecuta como un proceso de Node sobre stdio).
Un cliente compatible con MCP (Claude Code, Claude Desktop, Cursor, VS Code, …).
Datos accesibles por Infino — un directorio local, un bucket con credenciales disponibles en el entorno o un endpoint alojado de Infino Cloud con una clave API (consulta Backends de almacenamiento).
En la primera ejecución, el servidor descarga el modelo de embeddings local (~90 MB) una vez y lo almacena en caché; las ejecuciones posteriores son sin conexión para la incorporación.

Inicio rápido

El servidor es lanzado por tu cliente MCP a través de stdio — no lo ejecutas directamente en uso normal. Cada configuración de cliente sigue la misma forma: comando npx -y @infino-ai/mcp-server, con configuración proporcionada mediante variables de entorno. Establece INFINO_MCP_URI a los datos que quieres servir — una ruta local o un URI de bucket. Si se omite, el servidor usa un directorio persistente por usuario (~/.infino/mcp) para que los datos persistan entre reinicios; apunta INFINO_MCP_URI a tu propia ruta o bucket para servir datos existentes.

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

Para servir una base de datos alojada de Infino Cloud en su lugar, apunta INFINO_MCP_URI al endpoint https://<host>/<database> y proporciona tu clave API. Todo lo demás es 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_…"
  }
}

Las secciones siguientes muestran el lugar exacto donde cada cliente espera este bloque.

Plugin de Claude Code (instalación en un paso)

Para Claude Code, este repositorio también es un mercado de plugins. Instalar el plugin conecta el servidor MCP más una habilidad de cómo usar y un comando /infino-search en un solo paso — sin JSON que editar. Dentro de Claude Code:

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

Al habilitarlo, se te pedirá tu URI de datos de Infino (INFINO_MCP_URI) y, para Infino Cloud, tu clave API. Eso es todo: las herramientas infino_*, la habilidad using-infino y /infino-search <query> estarán disponibles. (Otros clientes: usa las configuraciones de Configuración del cliente a continuación.)

Configuración del cliente

Claude Code

Agrega el servidor con la CLI. Usa --scope user para hacerlo disponible en cada proyecto, o --scope project para comprometerlo al repositorio (escribe un .mcp.json compartido); el alcance predeterminado es local (solo este proyecto).

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

Agrega más opciones con banderas -e repetidas, p. ej. -e INFINO_MCP_VALIDATE=true. Verifica con:

claude mcp list
claude mcp get infino

Claude Desktop

Edita el archivo de configuración (créalo si no existe), luego reinicia completamente Claude Desktop.

SO	Ruta
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

Agrega el servidor a ~/.cursor/mcp.json (disponible en todos los proyectos) o <project>/.cursor/mcp.json (solo este proyecto), luego recarga. El formato coincide con Claude Desktop:

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

VS Code

VS Code (1.102+) lee servidores MCP desde .vscode/mcp.json en el espacio de trabajo (o tu mcp.json de usuario a través de la paleta de comandos → MCP: Open User Configuration). Ten en cuenta que la clave de nivel superior es servers y 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"
      }
    }
  }
}

Otros clientes MCP

Cualquier cliente que hable MCP sobre stdio funciona. Configúralo para lanzar:

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

Los registros se escriben en stderr para que nunca corrompan el flujo JSON-RPC en stdout — apunta la captura de registros de tu cliente allí al depurar.

Configuración

Toda la configuración es mediante variables de entorno — no hay archivos de configuración ni banderas de línea de comandos que gestionar.

Variables de entorno

Variable	Requerida	Predeterminado	Descripción
`INFINO_MCP_URI`	No	`~/.infino/mcp` (persistente)	Datos a servir: una ruta local (`/Users/me/.infino/memory`), un URI de bucket (`s3://…`, `az://…`) o un endpoint alojado (`https://<host>/<database>`, Infino Cloud). Si no se establece, se usa un directorio persistente por usuario (`~/.infino/mcp`) para que los datos persistan entre reinicios; se recurre a un catálogo efímero en proceso (`memory://`) solo si ese directorio no se puede crear.
`INFINO_API_KEY`	Con un URI alojado	—	Clave API (`inf_…`) para un endpoint `https://` alojado. Requerida cuando `INFINO_MCP_URI` es un URI `https://`; se ignora para conexiones locales y de almacenamiento de objetos.
`INFINO_MCP_EMBED_PROVIDER`	No	`local`	Proveedor de embeddings: `local` (Hugging Face transformers.js, sin clave, nada sale de la máquina) o `openai` (cualquier endpoint `/embeddings` compatible con OpenAI — OpenAI, la superficie `/openai/v1` de Azure OpenAI o un servidor compatible). Se infiere como `openai` cuando `INFINO_MCP_EMBED_BASE_URL` está establecido.
`INFINO_MCP_EMBED_BASE_URL`	Con `openai`	—	URL base de la API de embeddings compatible con OpenAI, p. ej. `https://api.openai.com/v1` o `https://<resource>.openai.azure.com/openai/v1`. El servidor hace POST a `<base>/embeddings`.
`INFINO_MCP_EMBED_API_KEY`	No	—	Clave API para el proveedor `openai`. Se envía como `Authorization: Bearer` y `api-key`, por lo que un valor funciona para OpenAI y Azure OpenAI. Omítela para llamar a un endpoint sin autenticación o con identidad ambiental.
`INFINO_MCP_EMBED_MODEL`	No	`Xenova/all-MiniLM-L6-v2` (local) · `text-embedding-3-small` (openai)	El modelo de embeddings. Para `local`, un modelo de extracción de características de Hugging Face; para `openai`, el nombre del modelo/implementación. Debe coincidir con el modelo que produjo los vectores almacenados de la tabla — y por lo tanto su dimensión de índice vectorial (p. ej. `text-embedding-3-small` es de 1536 dimensiones; el modelo local predeterminado es de 384 dimensiones).
`INFINO_MCP_VALIDATE`	No	desactivado	Cuando se establece (`1`/`true`/`yes`), sondea el almacén de objetos al inicio para que las credenciales incorrectas o un bucket inalcanzable fallen entonces en lugar de en la primera búsqueda.

Las credenciales de la nube se leen de las variables de entorno estándar del proveedor — el servidor las asigna a la configuración del almacén y no introduce variables de credenciales propias. Omítelas por completo para usar identidad de nube ambiental (un rol de instancia IAM o identidad administrada de Azure).

Sirviendo un catálogo incorporado con OpenAI / Azure OpenAI. Si tus tablas se vectorizaron con un modelo de embeddings alojado en lugar del local predeterminado, apunta el servidor a ese mismo modelo para que los vectores de consulta y documento se alineen:

"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"
}

El modelo debe coincidir con lo que produjo los vectores almacenados — un desajuste produce similitud sin sentido o un error de dimensión. La búsqueda por palabras clave y SQL no se ven afectadas por el incorporador.

Backend	Credenciales
AWS S3	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (+ `AWS_SESSION_TOKEN`, `AWS_REGION` si se usan)
Compatible con S3 (R2/MinIO/B2)	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` y `AWS_ENDPOINT_URL`
Azure Blob	`AZURE_STORAGE_ACCOUNT`, `AZURE_STORAGE_KEY`
Infino Cloud (alojado)	`INFINO_API_KEY` — no se necesitan credenciales de almacenamiento de objetos (la plataforma es dueña del almacenamiento)

Backends de almacenamiento

// 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_…"
}

En una conexión alojada, las herramientas de búsqueda, SQL y escritura se comportan exactamente como lo hacen localmente — la única diferencia es dónde viven los datos. La compactación y la recolección de basura se manejan del lado del servidor, por lo que no se exponen como operaciones del cliente. Ten en cuenta que la búsqueda semántica e híbrida aún incorporan consultas localmente en este servidor, por lo que INFINO_MCP_EMBED_MODEL debe coincidir con el modelo que produjo los vectores almacenados de la tabla alojada (consulta la nota de OpenAI / Azure OpenAI arriba) — esto importa especialmente cuando otra persona ingirió los datos.

Herramientas

Herramienta	Argumentos	Qué hace
`infino_semantic_search`	`table`, `query`, `k`, `column?`, `vectorColumn?`, `columns?`, `filter?`	Encuentra pasajes por significado — incrusta la consulta con un modelo local (sin clave) y clasifica por similitud vectorial. Maneja paráfrasis y sinónimos. `score` es una distancia (menor es más cercano). El `filter` opcional (`{column, query, mode?}`) restringe la clasificación a filas cuya columna de palabras clave coincide primero (un pre-filtro pushdown). El `columns` opcional elige qué campos devuelve cada resultado (por ejemplo, una ruta + rango de líneas para citar); por defecto es la columna de texto, con `_id` y `score` siempre incluidos.
`infino_keyword_search`	`table`, `query`, `k`, `column?`, `mode?`, `stats?`, `columns?`	Búsqueda de texto completo BM25 — para términos exactos, identificadores, códigos de error, nombres de productos. `score` es una relevancia (mayor es mejor). `mode` es `or` (predeterminado) o `and`; `stats` es `per_superfile` (predeterminado) o `global` para un idf único a nivel de tabla.
`infino_hybrid_search`	`table`, `query`, `k`, `column?`, `vectorColumn?`, `mode?`, `columns?`	Búsqueda fusionada de palabras clave + semántica en una sola pasada de clasificación — BM25 sobre la columna de texto combinado con similitud vectorial, de modo que las filas que coinciden con los términos literales y el significado se clasifican más alto. `score` es el rango fusionado (mayor es mejor).
`infino_token_match`	`table`, `query`, `column?`, `mode?`, `limit?`	Filtro de palabras clave sin clasificar — el conjunto de filas cuya columna de texto contiene el/los token(s). Úsalo cuando necesites las coincidencias, no un orden de relevancia.
`infino_exact_match`	`table`, `value`, `column?`, `limit?`	Filtro de igualdad exacta sin clasificar sobre una columna indexada (etiqueta, estado, cadena de id).
`infino_count`	`table`, `query`, `column?`, `mode?`	Cuenta cuántas filas coinciden con una consulta de palabras clave, sin recuperarlas — un recuento rápido sobre la columna de texto. Para las filas coincidentes usa `infino_keyword_search` o `infino_token_match`.
`infino_sql`	`query`, `embed?`	SQL para recuentos, filtros, uniones, agregados. Las funciones de tabla de búsqueda del motor se pueden invocar dentro; un marcador de posición `{{name}}` se rellena con el vector de `embed[name]`. Cualquier declaración única, incluido DDL/DML.
`infino_list_tables`	—	Lista las tablas en el catálogo conectado.
`infino_describe_table`	`table`	Nombres y tipos de columnas para una tabla.
`infino_create_database`	—	Aprovisiona la base de datos que nombra la conexión (Infino Cloud); una operación sin efecto que tiene éxito localmente. Idempotente.
`infino_create_table`	`table`, `columns`, `fts?`, `vector?`	Crea una tabla a partir de un descriptor `{column: type}`. Índices de texto completo en `fts` (predeterminado: cada columna `large_utf8`). `vector: true` agrega una columna `embedding` dimensionada al incrustador del servidor, con un índice de coseno.
`infino_drop_table`	`table`, `purge?`	Elimina una tabla y, por defecto, borra sus objetos de almacenamiento; `purge: false` solo anula el registro del nombre.
`infino_add_documents`	`table`, `documents`	Agrega filas (una llamada = una confirmación). Las filas sin vector se incrustan desde la columna de texto, todas en un lote; el resultado informa `appended` y `embedded`. Una clave que no es una columna es un error.
`infino_update_documents`	`table`, `predicate`, `documents`	Reemplaza las filas que coinciden con un predicado SQL con nuevos documentos, 1:1 (los vectores faltantes se incrustan). Solo almacenamiento duradero.
`infino_delete_documents`	`table`, `predicate`	Elimina las filas que coinciden con un predicado SQL. Solo almacenamiento duradero.

Los resultados de búsqueda devuelven valores completos de columna — el argumento columns es una proyección pasada directamente al motor (incrustado o alojado), de modo que cualquier columna de la tabla puede volver con cada resultado: ["id"] para resultados compactos con un k grande, ["id", "text"] para el texto completo junto con un id para citar, columnas de metadatos para filtrar. Por defecto es la columna de texto, con _id y score siempre incluidos, y nada se trunca jamás; para mantener los resultados pequeños, proyecta menos columnas o pide un k más pequeño. Cada respuesta de búsqueda también lleva score_kind, que indica si su score es una distancia (semántica: menor es más cercano) o una relevancia (palabras clave e híbrida: mayor es mejor).

Para recuperación simple, prefiere las herramientas de búsqueda dedicadas, que incrustan y proyectan por ti. infino_sql es para filtros, uniones y agregados, incluso sobre los resultados de una función de tabla de búsqueda, de modo que una consulta puede clasificar y agregar a la vez.

Escritura de datos

La ruta de escritura que sigue un agente, cada paso una llamada de herramienta y una confirmación:

infino_create_database si una base de datos alojada responde 404.
infino_create_table con una columna clave utf8, columnas de texto large_utf8 y vector: true para búsqueda semántica. El servidor dimensiona la columna de vectores a su incrustador; el agente nunca escribe una dimensión. Conserva el resultado: su campo indexes es el único registro de qué columnas están indexadas.
infino_add_documents, decenas de filas por llamada, incluyendo siempre la clave. Los vectores faltantes se incrustan en un lote.
Para reemplazar filas, infino_delete_documents por predicado de clave, luego agrega de nuevo. Para eliminar filas, verifica el predicado con infino_count primero.

Una llamada de herramienta lleva decenas de documentos. Para un corpus completo, usa la CLI infino (infino ingest acepta Parquet o NDJSON contra la misma URI) o un SDK. La CLI trae tus propios vectores como el motor, así que incluye la columna embedding en las filas o carga texto y busca por palabras clave.

No hay compuerta de escritura del lado del servidor, y la variable retirada INFINO_MCP_ENABLE_WRITES se ignora (el servidor lo dice en stderr si está configurada). En Infino Cloud, las capacidades de la clave de API limitan lo que la conexión puede hacer: una clave de solo lectura rechaza cada escritura, y el resultado de la herramienta dice que se acuñe una con capacidad de escritura. Localmente, apunta el servidor solo a datos que el agente pueda cambiar.

Seguridad y manejo de datos

Este servidor se ejecuta localmente, junto al cliente, y mantiene datos y credenciales en la máquina del usuario.

Ejecución local, sin listener entrante. Se ejecuta como subproceso de tu cliente MCP sobre stdio y no abre ningún listener de red. En el modo local/de bucket predeterminado no contacta ningún servicio remoto. Cuando INFINO_MCP_URI es un endpoint https:// alojado, hace llamadas TLS salientes a ese endpoint para servir búsquedas, SQL y (si está habilitado) escrituras — por lo que los datos en esas solicitudes llegan al servicio alojado que configuraste, y nada más.
No se envían datos para incrustar, por defecto. Con el proveedor predeterminado, la incrustación de consultas y documentos usa un modelo local, por lo que el texto nunca se envía a una API de incrustación de terceros y no hay clave de API de incrustación que aprovisionar o filtrar. En modo alojado, solo el vector resultante, no el texto, llega al endpoint de Infino Cloud. Si configuras el proveedor compatible con OpenAI, el texto que se incrusta se envía al endpoint que nombres.
Las credenciales permanecen en el entorno. Las credenciales de almacenamiento (AWS_*/AZURE_*) y la clave de API alojada (INFINO_API_KEY) se leen de variables de entorno y se usan solo para alcanzar el almacén o endpoint que configuraste. Nunca se registran ni se devuelven en la salida de la herramienta.
Quién puede escribir se decide fuera del servidor. El conjunto completo de herramientas, incluidas las escrituras, siempre está disponible para el agente. En Infino Cloud, las capacidades de la clave de API limitan lo que la conexión puede hacer (una clave de solo lectura rechaza cada escritura). Localmente, apunta el servidor solo a datos que el agente pueda cambiar. Cada herramienta lleva anotaciones MCP (readOnlyHint, destructiveHint) para que tu cliente pueda pedir confirmación en sus propios términos.
Privilegio mínimo. Apunta INFINO_MCP_URI al conjunto de datos más estrecho que la tarea necesite, y proporciona credenciales de almacenamiento limitadas a ese bucket/prefijo.

Cómo funciona la recuperación

La búsqueda semántica incrusta localmente con Hugging Face transformers.js (all-MiniLM-L6-v2, 384 dimensiones por defecto; anula con INFINO_MCP_EMBED_MODEL). El servidor incrusta tanto los documentos que ingiere (vía infino_add_documents) como tus consultas con el mismo modelo, para que se alineen en el mismo espacio vectorial.

Si cambias INFINO_MCP_EMBED_MODEL, el índice vectorial de la tabla debe coincidir con la dimensión del nuevo modelo — las incrustaciones producidas por diferentes modelos no son comparables, y una discrepancia de dimensión fallará en el momento de la búsqueda.

Solución de problemas

Síntoma	Causa probable / solución
El cliente no muestra herramientas de Infino	El servidor no se inició — revisa los registros MCP del cliente (stderr). Confirma que `npx` está en `PATH` y que `INFINO_MCP_URI` está configurado. Reinicia completamente el cliente después de editar la configuración.
`INFINO_MCP_URI is required`	La variable de entorno no llega al subproceso. En clientes GUI, el entorno debe estar dentro del bloque `env` del servidor (el proceso no heredará tu shell).
Una escritura dice que la clave "fue rechazada o carece de capacidad de escritura"	En Infino Cloud, la clave de API es de solo lectura (HTTP 403) o incorrecta. Acuña una clave con capacidad de escritura y reinicia el servidor con ella.
Una escritura dice "otro escritor ganó la carrera de confirmación"	Dos escritores golpearon la misma tabla a la vez y esta llamada no aterrizó. Reinténtala.
Primera consulta lenta	Descarga única del modelo de incrustación (~90 MB). Las ejecuciones posteriores usan la caché.
Error de autenticación contra una URI `https://` alojada	`INFINO_API_KEY` falta, es incorrecta o no tiene acceso a esa base de datos. Confirma la clave (`inf_…`) y que el último segmento de ruta de la URI sea una base de datos a la que puedas acceder.
Errores de dimensión / vector en búsqueda semántica	El índice vectorial de la tabla no coincide con la dimensión del modelo de incrustación. Re-ingiere, o configura `INFINO_MCP_EMBED_MODEL` al modelo con el que se construyó el índice.

Desarrollo local

El servidor depende del enlace Node @infino-ai/infino publicado, que se resuelve desde npm público como cualquier otra dependencia.

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

Apunta un cliente a node /absolute/path/dist/index.js sobre stdio para probar una compilación local, o usa el Inspector MCP:

npx @modelcontextprotocol/inspector node dist/index.js

Licencia

Apache-2.0