genie_mcp_server

The Genie MCP Server exposes an asynchronous API over the MCP StreamableHTTP Protocol to interact with Databricks Genie. It uses Starlette and Uvicorn to handle requests, and it includes components for Genie conversation flow and OAuth token management, enabling seamless querying and answer retrieval from Genie with robust authentication handling. You can send MCP requests to the deployed server’s API endpoint to start a session, send natural language queries, and receive Genie responses or data payloads.

Key components you’ll interact with are the Genie room logic (genie_room.py), which handles the actual Genie API calls and conversational state, and the token minter (token_minter.py), which manages OAuth minting and refreshing so requests remain authenticated. When you deploy the server, ensure SPACE_ID is configured to point to your Genie space; the server will automatically attach the appropriate credentials and route MCP requests to Genie.

Prerequisites:

• Python 3.8+ installed on your system or environment (preferred for async server and Starlette/Uvicorn).
• Access to a Python virtual environment (recommended).

Steps:

1. Clone the repository: git clone https://github.com/your-org/genie_mcp_server.git
2. Navigate to the project directory: cd genie_mcp_server
3. Create and activate a virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # on macOS/Linux venv\Scripts\activate # on Windows
4. Install dependencies: pip install -r requirements.txt
5. Configure environment variables (see app.yaml example in the repo): SPACE_ID=your_space_id
6. Run the server: python mcp_server.py
7. Verify the server starts and is listening on the expected port, then send MCP requests to the /api/mcp/ endpoint as configured in your deployment.

Environment variables and configuration:

• SPACE_ID is required to connect to your Genie space; set it in app.yaml or your deployment environment.
• The server handles OAuth token minting and refreshing automatically via token_minter.py; ensure your Databricks credentials allow token minting for Genie integration.
• If running behind a reverse proxy or load balancer, ensure the MCP endpoint (e.g., /api/mcp/) is reachable from clients and that TLS termination is configured as needed.
• Review app.yaml for deployment examples; adapt the SPACE_ID and any additional env vars to your environment.
• If you encounter authentication errors, confirm that the Databricks app permissions and Genie space access are properly configured and that token minting succeeds.