@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

Installation

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

# Build
npm run build

Environment Variables

Variable	Required	Description
OPENAI_API_KEY	Yes	Your OpenAI API key
OPENAI_API_BASE	No	Custom OpenAI API base URL (for proxies/compatible APIs)
PORT	No	HTTP server port (default: 3000)
HOST	No	HTTP server host (default: 127.0.0.1)

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)

Tool	Description
openai_create_vector_store	Create a new vector store
openai_retrieve_vector_store	Retrieve a vector store by ID
openai_update_vector_store	Update a vector store's name or metadata
openai_delete_vector_store	Delete a vector store
openai_list_vector_stores	List all vector stores with pagination and filtering
openai_search_vector_store	Search a vector store with a query string and optional filters

Files (4)

Tool	Description
openai_list_files	List files with filtering by purpose, status, and pagination
openai_retrieve_file	Retrieve file metadata by ID
openai_delete_file	Delete a file by ID
openai_retrieve_file_content	Download the content of a file by ID

Vector Store Files (6)

Tool	Description
openai_attach_file_to_vector_store	Attach a file to a vector store with optional attributes
openai_list_vector_store_files	List files in a vector store with filtering and pagination
openai_retrieve_vector_store_file	Retrieve a specific file in a vector store
openai_delete_vector_store_file	Remove a file from a vector store
openai_retrieve_vector_store_file_content	Download file content from a vector store
openai_update_vector_store_file_attributes	Update attributes on a vector store file

File Batches (4)

Tool	Description
openai_create_vector_store_file_batch	Create a batch of files for a vector store
openai_retrieve_vector_store_file_batch	Retrieve batch status and details
openai_cancel_vector_store_file_batch	Cancel an in-progress batch
openai_list_vector_store_file_batch_files	List files in a specific batch

Upload (1)

Tool	Description
openai_upload_file	Upload a file to OpenAI (for use with vector stores)

npm Scripts

Script	Description
npm start	Run stdio transport (local)
npm run start:http	Run HTTP transport (deployment)
npm run dev	Dev mode with watch (stdio)
npm run dev:http	Dev mode with watch (HTTP)
npm run build	Compile TypeScript
npm run clean	Remove dist/

License

MIT