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 — the retrieval layer for RAG, persistent agent memory, and search over your own files — 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.
• The index is a valid Parquet file. A table stores the data and its search indexes in plain Parquet on the storage — open the same file with DuckDB or pyarrow. No export, no lock-in.

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 ≥ 20 (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://<host>/<database> 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 <query> 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 <project>/.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=<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

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: