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": "node",
      "args": ["/absolute/path/to/vector-store-mcp/dist/stdio.js"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to your VS Code settings.json or .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "vector-store": {
        "command": "node",
        "args": ["/absolute/path/to/vector-store-mcp/dist/stdio.js"],
        "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 "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