@dotlab-hq/vector-store-mcp

MCP (Model Context Protocol) server for the OpenAI Vector Store API. Manage vector stores, files, file batches, and perform semantic search — all through a single MCP server.

Supports two transports:

• stdio — for local use with Claude Desktop, VS Code Copilot, or any MCP-compatible client

• HTTP (Streamable) — for deployment as a web service

Features

• 21 tools covering the full OpenAI Vector Store API

• Fully typed with TypeScript + Zod schema validation

• Uses the official OpenAI Node SDK

• Two entry points: local stdio and HTTP server

• Zero-config for local development

Related MCP server: Universal OpenAI Vector Store MCP Server

Installation

# Clone and install
git clone <repo-url>
cd vector-store-mcp
npm install

# Build
npm run build

Environment Variables

Usage

Local (stdio) — Recommended for Desktop Clients

# Run directly
npm start

# Or with dev watch mode
npm run dev

HTTP Server — For Deployment

# Start the HTTP server
npm run start:http

# Or with dev watch mode
npm run dev:http

The HTTP server exposes:

• GET /health — Health check

• POST /mcp — MCP Streamable HTTP endpoint

• CORS enabled for all origins in development

Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "vector-store": {
      "command": "npx",
      "args": ["-y", "@dotlab-hq/vector-store-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace root:

{
  "servers": {
    "vector-store": {
      "command": "npx",
      "args": ["-y", "@dotlab-hq/vector-store-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windows users: npx may fail with 'vector-store-mcp' is not recognized due to a known Windows shim resolution issue. To fix this, link the package globally once:

npm link @dotlab-hq/vector-store-mcp

Then use the direct command in .vscode/mcp.json:

{
  "servers": {
    "vector-store": {
      "command": "vector-store-mcp",
      "args": [],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

HTTP/Web Clients

With HTTP-based MCP, the server holds the credentials — the client only needs the URL. The API key and base URL are passed as environment variables when starting the server, not in the client config.

1. Start the server with your credentials:

# Pass env vars directly
OPENAI_API_KEY=sk-... npm run start:http

# Or use a .env file / shell profile to set them
export OPENAI_API_KEY=sk-...
export OPENAI_API_BASE=https://your-proxy.example.com/v1  # optional
npm run start:http
# Server running at http://127.0.0.1:3000/mcp

2. Connect from your MCP client — just the URL, no keys needed:

VS Code .vscode/mcp.json:

{
  "servers": {
    "vector-store": {
      "url": "http://127.0.0.1:3000/mcp",
      "type": "http"
    }
  }
}

Any MCP-compatible HTTP client:

POST http://127.0.0.1:3000/mcp
Content-Type: application/json

How it works: The server process reads OPENAI_API_KEY from its own environment and uses it for all OpenAI API calls. The MCP client never sees or transmits the key — it just sends tool requests to the server URL. This means you can run the server anywhere (local, cloud, Docker) and point multiple clients at it.

Programmatic API

You can also use this as a library:

import {
  McpServer,
  registerAllTools,
  getClient,
  resetClient,
} from "@dotlab-hq/vector-store-mcp";

const server = new McpServer({ name: "my-server", version: "1.0.0" });
registerAllTools(server);

Tools (21)

Vector Stores (6)

Files (4)

Vector Store Files (6)

File Batches (4)

Upload (1)

npm Scripts

License

MIT