Infino MCP server

An MCP server for 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` and listed on the official MCP Registry 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.
• The agent owns the data. Every tool, writes included, is always available. On Infino Cloud the API key's capabilities decide what a connection may do; every tool carries MCP annotations so your client can ask before a destructive call.
• 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
• Quick start
• Claude Code plugin (one-step install)
• Client setup
  • Claude Code
  • Claude Desktop
  • Cursor
  • VS Code
  • Other MCP clients
• Configuration
  • Environment variables
  • Storage backends
• Tools
• Security & data handling
• How retrieval works
• Troubleshooting
• Local development
• 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).
• 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.

{
  "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:///` endpoint and supply your API key. Everything

else is identical:

{
  "command": "npx",
  "args": ["-y", "@infino-ai/mcp-server"],
  "env": {
    "INFINO_MCP_URI": "https://api.platform.infino.ws/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, 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, for Infino Cloud, your API key. That's it: the `infino_*` tools, the `using-infino` skill, and `/infino-search ` are then available. (Other clients: use the 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).

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_VALIDATE=true`. Verify with:

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.

{
  "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 `/.cursor/mcp.json` (this project only), then reload. The format matches 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+) 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"`:

{
  "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=   (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

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:

"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 match what produced the stored vectors — a mismatch yields meaningless similarity or a dimension error. Keyword and SQL search are unaffected by the embedder.

Storage backends

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

On a hosted connection the search, SQL, and write tools all

behave exactly as they do locally — the only difference is where the data

lives. Compaction and garbage collection are handled server-side, so they are

not exposed as client operations. Note that semantic and hybrid search still

embed queries locally in this server, so `INFINO_MCP_EMBED_MODEL` must match

the model that produced the hosted table's stored vectors (see the OpenAI /

Azure OpenAI note above) — this matters especially when someone else ingested

the data.

Tools

Search hits return full column values — the `columns` argument is a projection passed straight to the engine (embedded or hosted), so any column in the table can come back with each hit: `["id"]` for compact hits at a large `k`, `["id", "text"]` for the full text alongside an id to cite, metadata columns for filtering. It defaults to the text column, with `_id` and `score` always included, and nothing is ever truncated; to keep results small, project fewer columns or ask for a smaller `k`. Every search response also carries `score_kind`, stating whether its `score` is a distance (semantic: lower is closer) or a relevance (keyword and hybrid: higher is better).

For plain retrieval prefer the dedicated search tools, which embed and project for you. `infino_sql` is for filters, joins, and aggregates, including over a search table function's results, so one query can rank and aggregate at once.

Writing data

The write path an agent follows, each step one tool call and one commit:

1. `infino_create_database` if a hosted database answers 404.

2. `infino_create_table` with a `utf8` key column, `large_utf8` text columns, and `vector: true` for semantic search. The server sizes the vector column to its embedder; the agent never types a dimension. Keep the result: its `indexes` field is the only record of which columns are indexed.

3. `infino_add_documents`, tens of rows per call, always including the key. Missing vectors are embedded in one batch.

4. To replace rows, `infino_delete_documents` by key predicate, then add again. To remove rows, check the predicate with `infino_count` first.

A tool call carries tens of documents. For a whole corpus, use the `infino` CLI (`infino ingest` takes Parquet or NDJSON against the same URI) or an SDK. The CLI is bring-your-own-vectors like the engine, so include the `embedding` column in the rows or load text and search by keyword.

There is no server-side write gate, and the retired `INFINO_MCP_ENABLE_WRITES` variable is ignored (the server says so on stderr if it is set). On Infino Cloud the API key's capabilities bound what the connection may do: a read-scoped key is refused every write, and the tool result says to mint one with write capability. Locally, point the server only at data the agent may change.

Security & data handling

This server runs locally, beside the client, and keeps data and credentials on the user's machine.

• Local execution, no inbound listener. It runs as a subprocess of your MCP client over stdio and opens no network listener. In the default local/bucket mode it contacts no remote service. When `INFINO_MCP_URI` is a hosted `https://` endpoint, it makes outbound TLS calls to that endpoint to serve searches, SQL, and (if enabled) writes — so the data in those requests reaches the hosted service you configured, and nothing else.
• No data sent for embedding, by default. With the default provider, query and document embedding uses a local model, so text is never sent to a third-party embedding API and there is no embedding API key to provision or leak. In hosted mode only the resulting vector, not the text, reaches the Infino Cloud endpoint. If you configure the OpenAI-compatible provider, the text being embedded is sent to the endpoint you name.
• Credentials stay in the environment. Storage credentials (`AWS_*`/`AZURE_*`) and the hosted API key (`INFINO_API_KEY`) are read from environment variables and used only to reach the store or endpoint you configured. They are never logged or returned in tool output.
• Who can write is decided outside the server. The full toolset, writes included, is always available to the agent. On Infino Cloud the API key's capabilities bound what the connection may do (a read-scoped key is refused every write). Locally, point the server only at data the agent may change. Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`) so your client can ask for confirmation on its own terms.
• Least privilege. Point `INFINO_MCP_URI` at the narrowest dataset the task needs, and supply storage credentials scoped to that bucket/prefix.

How retrieval works

Semantic search embeds locally with Hugging Face transformers.js (`all-MiniLM-L6-v2`, 384-dim by default; override with `INFINO_MCP_EMBED_MODEL`). The server embeds both the documents it ingests (via `infino_add_documents`) and your queries with the same model, so they align in the same vector space.

If you change `INFINO_MCP_EMBED_MODEL`, the table's vector index must match the new model's dimension — embeddings produced by different models are not comparable, and a dimension mismatch will fail at search time.

Troubleshooting

Local development

The server depends on the published `@infino-ai/infino` Node binding, which resolves from public npm like any other dependency.

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

Point a client at `node /absolute/path/dist/index.js` over stdio to dogfood a local build, or use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

License

Apache-2.0