Content
# OpenAI MCP Server
This MCP (Model Content Protocol) server provides access to OpenAI API functionality through HTTP, HTTPS, and STDIO transport modes.
## Features
- Multiple transport mode support (HTTP, HTTPS, and STDIO)
- Dynamic configuration through HTTP headers
- Automatic tool generation from API documentation
- Docker support for easy deployment
- Cross-platform Node.js binary compilation
- Production-ready deployment workflows
## Prerequisites
- Node.js 18.0.0 or later
- npm package manager
- pkg (for binary compilation, installed automatically by build script)
## Building the Project
### Using the Build Script (Recommended)
1. Make the build script executable:
```bash
chmod +x build.sh
```
2. Run the build script:
```bash
./build.sh
```
This will:
- Install dependencies with `npm install`
- Install pkg globally for binary compilation
- Build the project with `pkg` targeting Node.js 18 Linux x64
- Create executable binary in `bin/mcp-server`
- Generate `mcp-stdio.json` with correct paths
- Compress binary with GZip for smaller size
## Running the MCP Server
The server can run in three modes [STDIO, HTTP, HTTPS] based on the **TRANSPORT** environment variable:
### Transport Modes for Configuring MCP Servers
| Transport Mode | Use Case | Configuration File |
|----------------|----------|----------------------|
| **STDIO** | Direct integration | `mcp-stdio.json` |
| **STDIO/HTTP** | Directly run docker image | `mcp-docker.json` |
| **HTTP** | Web service on localhost/remote server | `mcp-http.json` |
| **HTTPS** | Secure web service with SSL/TLS | `mcp-https.json` |
### Method 1: Direct Binary/Node Execution
**Best for**: STDIO mode for local development and direct Cursor integration
**Step 1: Build the Server**
```bash
# Option A: Using build script (recommended)
chmod +x build.sh
./build.sh
# Option B: Manual build
npm install
npm install -g pkg
pkg main.js --targets node18-linux-x64 --output bin/mcp-server --no-warnings --compress GZip
chmod +x bin/mcp-server
```
**Step 2: Configure Cursor**
Use the generated `mcp-stdio.json` file:
```json
{
"mcpServers": {
"OpenAI-mcp-server-stdio": {
"command": "/path/to/your/project/bin/mcp-server",
"env": {
"API_BASE_URL": "https://your-api-base-url",
"BEARER_TOKEN": "your-bearer-token"
// Alternative authentication options (use only one):
// "API_KEY": "your-api-key",
// "BASIC_AUTH": "your-basic-auth-credentials",
}
}
}
}
```
### Method 2: Docker Mode (Containerized Deployment)
**Best for**: HTTP or HTTPS Docker mode for production deployment, scaling, and consistent environments
**Step 1: Build Docker Image**
```bash
docker build -t OpenAI-mcp-server .
```
***Option A: Let agent run the container directly:***
```json
{
"mcpServers": {
"OpenAI-mcp-server-docker": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-p", "8080:8080",
"-e", "API_BASE_URL=https://your.api.url",
"-e", "BEARER_TOKEN=your-token-here",
// Alternative authentication options (use any one):
// "-e", "API_KEY=your-api-key",
// "-e", "BASIC_AUTH=your-basic-auth-credentials",
"OpenAI-mcp-server"
]
}
}
}
```
***Option B: Run the container manually:***
```bash
docker run -d \
--name OpenAI-mcp-server \
-p 8080:8080 \
-e API_BASE_URL="https://your-api-base-url" \
-e BEARER_TOKEN="your-bearer-token" \
// Alternative authentication options (use any one):
// "-e", "API_KEY=your-api-key",
// "-e", "BASIC_AUTH=your-basic-auth-credentials",
-e TRANSPORT="http" \
-e PORT="8080" \
OpenAI-mcp-server
```
***Option C: Docker Compose (Recommended)***
```bash
# Build and start the container
docker-compose up --build
# Or run in detached mode
docker-compose up -d --build
```
**Step 2: Configure MCP Server**
- HTTP Mode `mcp-http.json`
```json
{
"mcpServers": {
"OpenAI-mcp-server-http": {
"url": "http://localhost:8080/mcp" or "http://remote-server:8080/mcp",
"headers": {
"API_BASE_URL": "https://your-api-base-url",
"BEARER_TOKEN": "your-bearer-token"
// Alternative authentication options (use any one):
// "API_KEY": "your-api-key",
// "BASIC_AUTH": "your-basic-auth-credentials",
}
}
}
}
```
- HTTPS Mode `mcp-https.json`
```json
{
"mcpServers": {
"OpenAI-mcp-server-https": {
"url": "https://localhost:8443/mcp" or "https://remote-server:8443/mcp",
"headers": {
"API_BASE_URL": "https://your-api-base-url",
"BEARER_TOKEN": "your-bearer-token",
"CERT_FILE": "./certs/cert.pem",
"KEY_FILE": "./certs/key.pem"
// Alternative authentication options (use any one):
// "API_KEY": "your-api-key",
// "BASIC_AUTH": "your-basic-auth-credentials",
}
}
}
}
```
#### Required Environment Variables for HTTPS Mode:
- `TRANSPORT`: Set to "http" or "https" **(Required)**
- `PORT`: Server port **(Required)**
- `CERT_FILE`: Path to SSL certificate file (for HTTPS mode)
- `KEY_FILE`: Path to SSL private key file (for HTTPS mode)
#### Configuration through HTTP Headers:
In HTTP mode, API configuration is provided via HTTP headers for each request:
- `API_BASE_URL`: **(Required)** Base URL for the API
- `BEARER_TOKEN`: Bearer token for authentication
- `API_KEY`: API key for authentication
- `BASIC_AUTH`: Basic authentication credentials
The server will start on the configured port with the following endpoints:
- `/mcp`: HTTP/HTTPS endpoint for MCP communication (requires API_BASE_URL header)
- `/`: Health check endpoint
**Note**: At least one authentication header (BEARER_TOKEN, API_KEY, or BASIC_AUTH) should be provided unless the API explicitly doesn't require authentication.
## Development
For development with auto-reload:
```bash
npm run dev
```
## Environment Variable Case Sensitivity
The server supports both uppercase and lowercase transport environment variables:
- `TRANSPORT` (uppercase) - checked first
- `transport` (lowercase) - fallback if uppercase not set
Valid values: "http", "HTTP", "https", "HTTPS", "stdio", or unset (defaults to STDIO)
## Authentication
### HTTP Mode
Authentication is provided through HTTP headers on each request:
- `BEARER_TOKEN`: Bearer token
- `API_KEY`: API key
- `BASIC_AUTH`: Basic authentication
### STDIO Mode
Authentication is provided through environment variables:
- `BEARER_TOKEN`: Bearer token
- `API_KEY`: API key
- `BASIC_AUTH`: Basic authentication
## Health Check
When running in HTTP mode, you can check server health at the root endpoint (`/`).
Expected response: `{"status":"ok"}`
## Transport Modes Summary
### HTTP Mode (TRANSPORT=http or TRANSPORT=HTTP)
- Uses HTTP server
- Configuration provided via HTTP headers for each request
- Requires API_BASE_URL header for each request
- Endpoint: `/mcp`
- Port configured via PORT environment variable (defaults to 8080)
### HTTPS Mode (TRANSPORT=https or TRANSPORT=HTTPS)
- Uses HTTPS server with SSL/TLS encryption
- Configuration provided via HTTP headers for each request
- Requires API_BASE_URL header for each request
- Endpoint: `/mcp`
- Port configured via PORT environment variable (defaults to 8443)
- **Requires SSL certificate and private key files (CERT_FILE and KEY_FILE)**
### STDIO Mode (TRANSPORT=stdio or unset)
- Uses standard input/output for communication
- Configuration through environment variables only
- Requires API_BASE_URL environment variable
- Suitable for command-line usage
