What is Openai Filesearch Mcp

openai-filesearch-mcp is a lightweight FastMCP service that allows users to query OpenAI’s File Search on a designated vector store, returning raw ranked chunks of data.

Use cases

Use cases include integrating with applications that need to retrieve and display relevant documents based on user queries, enhancing search functionalities in knowledge management systems, and supporting AI-driven research tools.

How to use

To use openai-filesearch-mcp, clone the repository, install dependencies, configure the ‘config.json’ with your Vector Store ID, and set your OpenAI API Key in the environment variables. Then, you can call the ‘retrieveDocs(question)’ RPC to get the results.

Key features

Key features include acting as a proxy to OpenAI’s ‘/v1/responses’ endpoint, returning raw chunks as JSON, handling transient errors with retry logic, and optional verbose logging for debugging.

Where to use

openai-filesearch-mcp can be used in various fields such as data retrieval, natural language processing, and applications requiring efficient document search capabilities.

FileSearch MCP Server

A minimal FastMCP 2.x server in TypeScript that exposes one RPC—retrieveDocs(question)—which returns raw ranked chunks from OpenAI File Search.

Features

• Acts as a simple proxy to OpenAI’s /v1/responses endpoint using the file_search tool.
• Reads OPENAI_API_KEY from environment variables.
• Reads vectorStoreId from config.json.
• Uses FastMCP 2.x with addTool and ctx.log.
• Returns raw chunks ({ id, text, score }[]) as a JSON string, extracted from file_search_call.results.
• Includes robustness features: 30s timeout, retry logic (3 attempts) for transient errors (429, 5xx, network), and structured error reporting.
• Optional verbose logging via DEBUG_OPENAI environment variable.

Prerequisites

• Node.js (v18 or later recommended)
• npm (or pnpm/yarn)
• An OpenAI API Key
• An existing OpenAI Vector Store ID
• Git (for cloning)

Setup

1. Clone the repository (if applicable):

   # git clone <repository-url>
   # cd filesearch-mcp-server
   

2. Install dependencies: Installs required packages.

   npm install
   

3. Configure:

   • config.json: Copy config.template.json to config.json and add your Vector Store ID.

     cp config.template.json config.json
     

     Then edit config.json:

     {
       "vectorStoreId": "vs_YOUR_VECTOR_STORE_ID"
     }
     

     (Replace vs_YOUR_VECTOR_STORE_ID with your actual ID. This file is ignored by git via .gitignore.)

   • Environment Variables: Create a .env file (or set environment variables directly). You can copy the example:

     cp .env.example .env
     

     Then edit .env with your API key:

     # Required: Your OpenAI API Key
     OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
     
     # Optional: Set to "true" or "1" for verbose OpenAI API response logging
     # DEBUG_OPENAI=false
     

     (This file is ignored by git via .gitignore.)

     Alternatively, configure via Cline MCP Settings (cline_mcp_setting.json):

     {
       "servers": [
         {
           "id": "filesearch-mcp-server",
           "command": "npm start",
           "working_directory": "path/to/filesearch-mcp-server",
           "environment": {
             "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
             "DEBUG_OPENAI": "false"
           }
         }
       ]
     }
     

4. Build the TypeScript code:

   npm run build
   

Running the Server

npm start

This command runs node dist/server.js, starting the server using the stdio transport (default). It listens for MCP requests on standard input/output, making it suitable for use with Cline or other MCP clients expecting stdio communication.

Development

• Build: npm run build (Compiles TypeScript to dist/)
• Format: npm run format (Formats code with Prettier)
• Lint: npm run lint (Checks code style with ESLint)
• Watch & Run: npm run dev (Watches for changes, rebuilds, and restarts the server)

Chunk Structure

The server extracts chunks from the output[*].file_search_call.results field in the OpenAI API response. Each chunk in the returned JSON array follows the Chunk interface: { id: string, text: string, score: number }. The id is taken from the result object’s id field (with a fallback), text is the chunk content, and score is the relevance score provided by OpenAI.

License

This project is licensed under the MIT License - see the LICENSE file for details.