😎 A VIBE coding presentation ;) | Google Gemini | Kilo

---

🚀 MCP to OpenAPI relay server

Proxy to facilitate communication between AI agents and remote OpenAPI compatible tool server using Model Context Protocol. Acts as an unified secure gateway with observable activity.

🤖 AI Agent
             ⇌  🚀 MCP Relay
                              ⇌  🔨 OpenAPI service

😊 Solving real life probelm

I developed a bunch of tools with OpenAPI compatible API to integrate with Open WebUI and it was working great; until one day I discovered that the modern AI agents has support for MCP Server only! The idea to to convert all my PHP code to Python was a nightmare :( So I decided to develop an MCP Server that permanently pipes tool calls to the existing OpenAPI compatible API server with minimal near zero configuration. It was a serious relief being a PHP developer with zero Python knowledge :)

✨ Features

• ➰ Unified Gateway: Seamlessly bridges MCP requests to a remote OpenAPI backend.
• 💓 Progress Heartbeats: Implements dynamic stack inspection to report real-time progress updates back to the AI Agent during long-running tool calls.
• 🔄 Schema Drift Monitoring: Automatically detects changes in remote OpenAPI schema.
• 🔒 Secure Authentication: Integrates Nginx for pre-request token validation, ensuring only authorized requests reach the Python backend.
• 🐳 High Availability: Configured with Docker and Nginx for reliable deployment and load handling.
• ✍ Freedom of language: Keep developing your OpenAPI compatible tools in your choice of language, no more boundaries.

🛠️ Technology Stack

• Backend: Python, BASH
• Proxy/Gateway: NginX
• Containerization: Docker, Docker Compose
• Configuration: Environment Variables (.env)

⚙️ Getting Started

Prerequisites

Ensure you have the following installed on your system:

• Docker
• Docker Compose
• A valid OpenAPI backend service running and accessible at the configured API_BASE_URL.

Installation

• Clone the Repository: git clone https://forgejo.piti.cloud/joy/MCP2OpenAPI.git.

• Configure Environment Variables

  • Rename .env.example file to .env and set following environment variables
    • MCP2OPENAPI_API_BASE_URL: Base URL to the remote OpenAPI service. Example: http://API_SERVER:PORT (do not use trailing slash)
    • MCP2OPENAPI_API_BEARER_TOKEN: Bearer authentication token for remote OpenAPI server (if required)
    • MCP2OPENAPI_API_TIMEOUT: How long the MCP Server should wait for a response from the remote OpenAPI service (e.g., 9999 seconds)
    • MCP2OPENAPI_DEBUG: Set to true for verbose Docker container logging

• Run container: docker-compose up -d --build

Usage

Insecure connection without authorization

MCP server exposes MCP interface at: http://MCP2OPENAPI_IP_HTTP:MCP2OPENAPI_PORT_HTTP/mcp/. Add this MCP Server URL to your AI agent/client and it should automatically list all available OpenAPI compatible tools.

• Example: http://192.168.1.211:8001/mcp/
• Default port: 8001 (check .env file)
• You still need the Bearer authorization token for MCP2OPENAPI_API_BEARER_TOKEN if your remote OpenAPI service requires it

Secure connection (recommended)

The MCP Server also comes with Bearer token based secure access for AI agent/client. Use http://MCP2OPENAPI_SECURE_ACCESS_IP_HTTP:MCP2OPENAPI_SECURE_ACCESS_PORT_HTTP/mcp/ to connect your AI agent/client with preconfigured Bearer tokens in NginX/authorization.conf file.

• Example: http://192.168.1.211:65482/mcp/
• Bearer token: Get from NginX/authorization.conf file
• Default port: 65482 (check .env file)

❓ Frequently Asked Questions (FAQ)

How to check the remote OpenAPI endpoint is functional?

Simply type in your OpenAPI compatible API schema URL in the browser and check if it returns a valid schema. You may use PostMan if it requires Bearer authorization.

Example: http://API_SERVER:PORT/openapi.json

What happens if the remote OpenAPI schema changes?

The MCP Server should automatically pick up the remote OpenAPI schema changes at a certain interval as configured in the .env file; default is 30 seconds. You do not need to do anything with the setup or AI agent/client. The process is completely automatic.

How to secure the connection between AI agent and this MCP Server?

Update the NginX/authorization.conf file with your custom Bearer tokens. Use any of the tokens you set there in your AI agent/client to connect to this MCP Server. Note that this authorization token is for your AI agent/client, it has nothing to do with the authorization for the remote OpenAPI service.

⚠️ Troubleshooting

• Schema Fetch Failure: Ensure the remote OpenAPI service is available at startup to allow the initial schema fetch.
• Connection Refused: Verify that the API_BASE_URL in .env points to a running and reachable backend service.
• 401 Unauthorized: You must use one of the Bearer tokens as defined in NginX/authorization.conf file. This is for secure connection between the AI agent and this MCP Server. Do not confuse it with the authorization token for the remote OpenAPI server.