infino-mcp

# Infino MCP server

[![npm](https://img.shields.io/npm/v/@infino-ai/mcp-server.svg)](https://www.npmjs.com/package/@infino-ai/mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.infino--ai%2Fmcp--server-blue)](https://registry.modelcontextprotocol.io/?search=io.github.infino-ai/mcp-server)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-green.svg)](./LICENSE)

An [MCP](https://modelcontextprotocol.io) server for [Infino](https://github.com/infino-ai/infino) — it lets an AI agent run **keyword**, **semantic**, **hybrid**, and **SQL** retrieval over your data on object storage, from any MCP-compatible client (Claude Code, Claude Desktop, Cursor, VS Code, and others). Published on npm as [`@infino-ai/mcp-server`](https://www.npmjs.com/package/@infino-ai/mcp-server) and listed on the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.infino-ai/mcp-server` (which propagates to catalogs like Smithery, Glama, and PulseMCP).

- **Local embeddings, no key.** Semantic search embeds queries with a local model — nothing leaves the machine for embedding.
- **Read-only by default.** Writes and full SQL are opt-in behind a single environment flag.
- **Local or hosted.** Point it at a local path, your own bucket (S3, Azure, or any S3-compatible store), or a hosted Infino Cloud endpoint with an API key.

---

## Contents

- [Requirements](#requirements)
- [Quick start](#quick-start)
- [Claude Code plugin (one-step install)](#claude-code-plugin-one-step-install)
- [Client setup](#client-setup)
  - [Claude Code](#claude-code)
  - [Claude Desktop](#claude-desktop)
  - [Cursor](#cursor)
  - [VS Code](#vs-code)
  - [Other MCP clients](#other-mcp-clients)
- [Configuration](#configuration)
  - [Environment variables](#environment-variables)
  - [Storage backends](#storage-backends)
- [Tools](#tools)
- [Security & data handling](#security--data-handling)
- [How retrieval works](#how-retrieval-works)
- [Troubleshooting](#troubleshooting)
- [Local development](#local-development)
- [License](#license)

---

## Requirements

- **Node.js ≥ 18** (the server runs as a Node process over stdio).
- **An MCP-compatible client** (Claude Code, Claude Desktop, Cursor, VS Code, …).
- **Data reachable by Infino** — a local directory, a bucket with credentials available in the environment, or a hosted Infino Cloud endpoint with an API key (see [Storage backends](#storage-backends)).
- On first run the server downloads the local embedding model (~90 MB) once and caches it; subsequent runs are offline for embedding.

---

## Quick start

The server is launched by your MCP client over stdio — you don't run it directly in normal use. Every client config follows the same shape: command `npx -y @infino-ai/mcp-server`, with configuration supplied via environment variables. Set `INFINO_MCP_URI` to the data you want to serve — a local path or a bucket URI. If it's omitted, the server uses a durable per-user directory (`~/.infino/mcp`) so data persists across restarts; point `INFINO_MCP_URI` at your own path or bucket to serve existing data.

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

To serve a **hosted Infino Cloud** database instead, point `INFINO_MCP_URI` at
the `https://<host>/<database>` endpoint and supply your API key — everything
else (the tools, the read-only default) is identical:

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

The sections below show the exact place each client expects this block.

---

## Claude Code plugin (one-step install)

For [Claude Code](https://claude.com/claude-code), this repo is also a plugin marketplace. Installing the plugin wires up the MCP server **plus** a how-to-use skill and an `/infino-search` command in one step — no JSON to edit. Inside Claude Code:

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

On enable you'll be prompted for your **Infino data URI** (`INFINO_MCP_URI`) and whether to **enable writes**. That's it — the `infino_*` tools, the `using-infino` skill, and `/infino-search <query>` are then available. (Other clients: use the [Client setup](#client-setup) configs below.)

---

## Client setup

### Claude Code

Add the server with the CLI. Use `--scope user` to make it available in every project, or `--scope project` to commit it to the repo (writes a shared `.mcp.json`); the default scope is `local` (this project only).

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

Add more knobs with repeated `-e` flags, e.g. `-e INFINO_MCP_ENABLE_WRITES=true`. Verify with:

```sh
claude mcp list
claude mcp get infino
```

### Claude Desktop

Edit the configuration file (create it if it doesn't exist), then fully restart Claude Desktop.

| OS | Path |
| --- | --- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

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

### Cursor

Add the server to **`~/.cursor/mcp.json`** (available in all projects) or **`<project>/.cursor/mcp.json`** (this project only), then reload. The format matches Claude Desktop:

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

### VS Code

VS Code (1.102+) reads MCP servers from **`.vscode/mcp.json`** in the workspace (or your user `mcp.json` via the command palette → *MCP: Open User Configuration*). Note the top-level key is `servers` and each entry declares `"type": "stdio"`:

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

### Other MCP clients

Any client that speaks MCP over stdio works. Configure it to launch:

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

Logs are written to **stderr** so they never corrupt the JSON-RPC stream on stdout — point your client's log capture there when debugging.

---

## Configuration

All configuration is via environment variables — there are no config files and no command-line flags to manage.

### Environment variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `INFINO_MCP_URI` | No | `~/.infino/mcp` (persistent) | Data to serve: a local path (`/Users/me/.infino/memory`), a bucket URI (`s3://…`, `az://…`), or a hosted endpoint (`https://<host>/<database>`, Infino Cloud). If unset, a durable per-user directory (`~/.infino/mcp`) is used so data persists across restarts; it falls back to an ephemeral in-process catalog (`memory://`) only if that directory can't be created. |
| `INFINO_API_KEY` | With a hosted URI | — | API key (`inf_…`) for a hosted `https://` endpoint. Required when `INFINO_MCP_URI` is an `https://` URI; ignored for local and object-storage connections. |
| `INFINO_MCP_ENABLE_WRITES` | No | _off_ | When set (`1`/`true`/`yes`), exposes `infino_add_documents` **and** lets `infino_sql` run DDL/DML. Omit for a strictly read-only server. |
| `INFINO_MCP_EMBED_PROVIDER` | No | `local` | Embedding provider: `local` (Hugging Face transformers.js, no key, nothing leaves the machine) or `openai` (any OpenAI-compatible `/embeddings` endpoint — OpenAI, Azure OpenAI's `/openai/v1` surface, or a compatible server). Inferred as `openai` when `INFINO_MCP_EMBED_BASE_URL` is set. |
| `INFINO_MCP_EMBED_BASE_URL` | With `openai` | — | Base URL of the OpenAI-compatible embeddings API, e.g. `https://api.openai.com/v1` or `https://<resource>.openai.azure.com/openai/v1`. The server POSTs to `<base>/embeddings`. |
| `INFINO_MCP_EMBED_API_KEY` | No | — | API key for the `openai` provider. Sent as both `Authorization: Bearer` and `api-key`, so one value works for OpenAI and Azure OpenAI. Omit to call an unauthenticated or ambient-identity endpoint. |
| `INFINO_MCP_EMBED_MODEL` | No | `Xenova/all-MiniLM-L6-v2` (local) · `text-embedding-3-small` (openai) | The embedding model. For `local`, a Hugging Face feature-extraction model; for `openai`, the model/deployment name. **Must match the model that produced the table's stored vectors** — and therefore its vector-index dimension (e.g. `text-embedding-3-small` is 1536-dim; the default local model is 384-dim). |
| `INFINO_MCP_VALIDATE` | No | _off_ | When set (`1`/`true`/`yes`), probes the object store at startup so bad credentials or an unreachable bucket fail then instead of on the first search. |

Cloud credentials are read from the standard provider environment variables — the server maps them to the store's config and introduces no credential vars of its own. Omit them entirely to use ambient cloud identity (an IAM instance role or Azure managed identity).

**Serving a catalog embedded with OpenAI / Azure OpenAI.** If your tables were vectorized with a hosted embedding model rather than the local default, point the server at that same model so query and document vectors align:

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

The model must