https://github.com/teabranch/open-responses-server
Wraps any OpenAI API interface as Responses with MCPs support so it supports Codex. Adding any missing stateful features. Ollama and Vllm compliant.
https://github.com/teabranch/open-responses-server
ai codex generative-ai mcp mcp-client openai openai-api openai-codex openai-codex-cli openai-codex-integration responses-api
Last synced: 23 days ago
JSON representation
Wraps any OpenAI API interface as Responses with MCPs support so it supports Codex. Adding any missing stateful features. Ollama and Vllm compliant.
- Host: GitHub
- URL: https://github.com/teabranch/open-responses-server
- Owner: teabranch
- License: mit
- Created: 2025-04-18T00:01:35.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-11-05T23:17:23.000Z (6 months ago)
- Last Synced: 2026-03-29T14:49:49.990Z (29 days ago)
- Topics: ai, codex, generative-ai, mcp, mcp-client, openai, openai-api, openai-codex, openai-codex-cli, openai-codex-integration, responses-api
- Language: Python
- Homepage: https://teabranch.github.io/open-responses-server/
- Size: 478 KB
- Stars: 153
- Watchers: 5
- Forks: 20
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/SECURITY.md
Awesome Lists containing this project
README
# 🚀 open-responses-server
A plug-and-play server that speaks OpenAI’s Responses API—no matter which AI backend you’re running.
Ollama? vLLM? LiteLLM? Even OpenAI itself?
This server bridges them all to the OpenAI ChatCompletions & Responses API interface.
In plain words:
👉 Want to run OpenAI’s Coding Assistant (Codex) or other OpenAI API clients against your own models?
👉 Want to experiment with self-hosted LLMs but keep OpenAI’s API compatibility?
This project makes it happen.
It handles stateful chat, tool calls, and future features like file search & code interpreter—all behind a familiar OpenAI API.
⸻
# ✨ Why use this?
✅ Acts as a drop-in replacement for OpenAI’s Responses API.
✅ Lets you run any backend AI (Ollama, vLLM, Groq, etc.) with OpenAI-compatible clients.
✅ MCP support around both Chat Completions and Responses APIs
✅ Supports OpenAI’s new Coding Assistant / Codex that requires Responses API.
✅ Built for innovators, researchers, OSS enthusiasts.
✅ Enterprise-ready: scalable, reliable, and secure for production workloads.
⸻
🔥 What’s in & what’s next?
✅ Done 📝 Coming soon
- ✅ Tool call support .env file support
- ✅ Manual & pipeline tests
- ✅ Docker image build
- ✅ PyPI release
- 📝 Persistent state (not just in-memory)
- ✅ CLI validation
- 📝 hosted tools:
- ✅ MCPs support
- 📝 Web search: crawl4ai
- 📝 File upload + search: graphiti
- 📝 Code interpreter
- 📝 Computer use APIs
⸻
# 🏗️ Quick Install
Latest release on PyPI:
```
pip install open-responses-server
```
Or install from source:
```
pip install uv
uv venv
uv pip install .
uv pip install -e ".[dev]" # dev dependencies
```
Run the server:
```
# Using CLI tool (after installation)
otc start
# Or directly from source
uv run src/open_responses_server/cli.py start
```
Docker deployment:
```
# Run with Docker
docker run -p 8080:8080 \
-e OPENAI_BASE_URL_INTERNAL=http://your-llm-api:8000 \
-e OPENAI_BASE_URL=http://localhost:8080 \
-e OPENAI_API_KEY=your-api-key \
ghcr.io/teabranch/open-responses-server:latest
```
Docker images are available for linux/amd64, linux/arm64, and linux/arm/v7 architectures.
Works great with docker-compose.yaml for Codex + your own model.
⸻
# 🛠️ Configure
Minimal config to connect your AI backend:
```
OPENAI_BASE_URL_INTERNAL=http://localhost:8000 # Your LLM backend (Ollama typically on :11434, vLLM on :8000)
OPENAI_BASE_URL=http://localhost:8080 # This server's endpoint
OPENAI_API_KEY=sk-mockapikey123456789 # Mock key tunneled to backend
MCP_SERVERS_CONFIG_PATH=./mcps.json # Path to mcps servers json file
```
Server binding:
```
API_ADAPTER_HOST=0.0.0.0
API_ADAPTER_PORT=8080
```
Streaming and connection:
```
STREAM_TIMEOUT=120.0 # HTTP timeout (seconds) for streaming requests
HEARTBEAT_INTERVAL=15.0 # SSE keepalive interval (seconds)
```
Conversation and tool handling:
```
MAX_CONVERSATION_HISTORY=100 # Max stored conversation entries
MAX_TOOL_CALL_ITERATIONS=25 # Max tool-call loop iterations
MCP_TOOL_REFRESH_INTERVAL=10 # Seconds between MCP tool cache refreshes
```
Logging:
```
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FILE_PATH=./log/api_adapter.log # Path to log file
```
Configure with CLI tool:
```
# Interactive configuration setup
otc configure
```
Verify setup:
```
# Check if the server is working
curl http://localhost:8080/v1/models
```
⸻
# 💬 We’d love your support!
If you think this is cool:
⭐ Star the repo.
🐛 Open an issue if something’s broken.
🤝 Suggest a feature or submit a pull request!
This is early-stage but already usable in real-world demos.
Let’s build something powerful—together.
## Star History
[](https://www.star-history.com/#TeaBranch/open-responses-server&Date)
# Projects using this middleware
- [Agentic Developer MCP Server](https://github.com/teabranch/agentic-developer-mcp) - a wrapper around Codex, transforming Codex into an agentic developer node over a folder. Together with this (ORS) repo, it becomes a link in a tree/chain of developers.
- [Nvidia jetson devices](https://github.com/OriNachum/autonomous-intelligence/tree/main/local-codex) - docker compose with ollama
⸻
# 📚 Citations & inspirations
## Referenced projects
- [SearXNG MCP](https://github.com/ihor-sokoliuk/mcp-searxng)
- UncleCode. (2024). Crawl4AI: Open-source LLM Friendly Web Crawler & Scraper [Computer software]. GitHub. [Crawl4AI repo](https://github.com/unclecode/crawl4ai)
## Cite this project
### Code citation
```
@software{open-responses-server,
author = {TeaBranch},
title = {open-responses-server: Open-source server bridging any AI provider to OpenAI’s Responses API},
year = {2025},
publisher = {GitHub},
journal = {GitHub Repository},
howpublished = {\url{https://github.com/teabranch/open-responses-server}},
commit = {use the commit hash you’re working with}
}
```
### Text citation
TeaBranch. (2025). open-responses-server: Open-source server the serves any AI provider with OpenAI ChatCompletions as OpenAI's Responses API and hosted tools. [Computer software]. GitHub. https://github.com/teabranch/open-responses-server
# Links:
- [Python library](https://pypi.org/project/open-responses-server)
- [GitHub repository](https://github.com/teabranch/open-responses-server)
- [GitHub Pages](https://teabranch.github.io/open-responses-server)
# Naming history
This repo had changed names:
- openai-responses-server (Changed to avoid brand name OpenAI)
- open-responses-server