feat: remote MCP server via Streamable HTTP + api_keys migration (OPE-91)

Phase 1 of MCP dogfooding. Converts the MCP server from stdio-only
to dual transport: stdio for local dev, streamable-http for remote.

Changes:
- server.py: Rewritten with FastMCP, dual transport support
  - stdio mode: same as before (Claude Desktop config)
  - streamable-http mode: remote deployment for Claude.ai Connectors
  - /health endpoint for Railway health checks
  - /mcp endpoint for MCP protocol (Streamable HTTP)
  - CLI: python server.py --transport http
  - Env: MCP_TRANSPORT=streamable-http

- config.py: Added TRANSPORT, HOST, PORT config from env vars
- requirements.txt: Added uvicorn, bumped mcp>=1.25.0
- Dockerfile: New, for Railway deployment of MCP service
- .env.example: Updated with transport config

- supabase/migrations/004_api_keys.sql: Creates api_keys table
  for MCP authentication (ci_xxx format, SHA-256 hashed, RLS)

Deployment steps in PR description.

Author: DevanshuNEU

mcp-server/.env.example

@@ -1,3 +1,10 @@
 # Backend API Configuration
-API_KEY=your-api-key-here
-BACKEND_API_URL=http://localhost:8000
+BACKEND_API_URL=https://api.opencodeintel.com
+API_KEY=ci_your-api-key-here
+
+# Transport: "stdio" for local dev, "streamable-http" for remote
+MCP_TRANSPORT=stdio
+
+# Server host/port (only used for streamable-http transport)
+MCP_HOST=0.0.0.0
+PORT=8080

mcp-server/Dockerfile

@@ -0,0 +1,17 @@
+# MCP Server Dockerfile - Remote Streamable HTTP deployment
+FROM python:3.13-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Railway sets PORT automatically
+ENV MCP_TRANSPORT=streamable-http
+ENV MCP_HOST=0.0.0.0
+
+EXPOSE 8080
+
+CMD ["python", "server.py"]

mcp-server/config.py

@@ -13,4 +13,9 @@
 API_KEY = os.getenv("API_KEY", "")
 
 SERVER_NAME = "codeintel-mcp"
-SERVER_VERSION = "0.4.0"
+SERVER_VERSION = "0.5.0"
+
+# Transport: "stdio" for local, "streamable-http" for remote deployment
+TRANSPORT = os.getenv("MCP_TRANSPORT", "stdio")
+HOST = os.getenv("MCP_HOST", "0.0.0.0")
+PORT = int(os.getenv("PORT", "8080"))

mcp-server/requirements.txt

@@ -1,8 +1,9 @@
 # MCP Server Dependencies
-mcp>=1.0.0
+mcp>=1.25.0
 httpx>=0.27.0
 python-dotenv>=1.0.0
 pydantic>=2.0.0
+uvicorn>=0.30.0
 
 # Test Dependencies
 pytest>=8.0.0

mcp-server/server.py

@@ -1,54 +1,89 @@
 #!/usr/bin/env python3
 """CodeIntel MCP Server entry point.
 
-Provides codebase intelligence tools for LLMs via Model Context Protocol.
-All tool definitions, handlers, and formatters are in their own modules.
+Supports two transport modes:
+  stdio            - Local dev, Claude Desktop config (default)
+  streamable-http  - Remote deployment, Claude.ai Connectors
+
+Usage:
+  python server.py                    # stdio (default)
+  python server.py --transport http   # streamable HTTP on $PORT
 """
-import asyncio
+import sys
 
-from mcp.server import Server
-from mcp.server.models import InitializationOptions, ServerCapabilities
-import mcp.server.stdio
+from mcp.server.fastmcp import FastMCP
 import mcp.types as types
+from starlette.routing import Route
+from starlette.responses import JSONResponse
 
-from config import SERVER_NAME, SERVER_VERSION
+from config import SERVER_NAME, SERVER_VERSION, TRANSPORT, HOST, PORT
 from tools import get_tool_schemas
 from handlers import call_tool
-from api_client import close_client
 
-server = Server(SERVER_NAME)
+mcp = FastMCP(
+    name=SERVER_NAME,
+    instructions=(
+        "CodeIntel provides semantic code search, dependency analysis, "
+        "and codebase intelligence. Use list_repositories first to find "
+        "repo IDs, then search_code or get_codebase_dna for context."
+    ),
+    host=HOST,
+    port=PORT,
+    streamable_http_path="/mcp",
+    stateless_http=True,
+    log_level="INFO",
+)
+
+# Register tools at the low-level MCP server layer.
+# FastMCP's @tool decorator infers schemas from function signatures,
+# but we have well-tested schemas in tools.py and dispatch in handlers.py.
+_server = mcp._mcp_server
 
 
-@server.list_tools()
+@_server.list_tools()
 async def handle_list_tools() -> list[types.Tool]:
     """Return all available tool schemas."""
     return get_tool_schemas()
 
 
-@server.call_tool()
+@_server.call_tool()
 async def handle_call_tool(
     name: str, arguments: dict | None
 ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
     """Dispatch tool calls to the handler layer."""
     return await call_tool(name, arguments)
 
 
-async def main() -> None:
-    """Run the MCP server over stdio transport."""
-    try:
-        async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
-            await server.run(
-                read_stream,
-                write_stream,
-                InitializationOptions(
-                    server_name=SERVER_NAME,
-                    server_version=SERVER_VERSION,
-                    capabilities=ServerCapabilities(tools={}),
-                ),
-            )
-    finally:
-        await close_client()
+# Health check for Railway/load balancers
+async def _health(request):
+    return JSONResponse({"status": "ok", "server": SERVER_NAME, "version": SERVER_VERSION})
+
+
+def _get_http_app():
+    """Build the Starlette app with health check + MCP endpoint."""
+    app = mcp.streamable_http_app()
+    app.routes.insert(0, Route("/health", _health, methods=["GET"]))
+    return app
+
+
+def main():
+    """Run with configured transport."""
+    transport = TRANSPORT
+
+    # CLI override: --transport http
+    if "--transport" in sys.argv:
+        idx = sys.argv.index("--transport")
+        if idx + 1 < len(sys.argv):
+            arg = sys.argv[idx + 1]
+            transport = "streamable-http" if arg in ("http", "streamable-http") else arg
+
+    if transport == "streamable-http":
+        import uvicorn
+        print(f"Starting {SERVER_NAME} v{SERVER_VERSION} on {HOST}:{PORT}/mcp")
+        uvicorn.run(_get_http_app(), host=HOST, port=PORT)
+    else:
+        mcp.run(transport="stdio")
 
 
 if __name__ == "__main__":
-    asyncio.run(main())
+    main()

supabase/migrations/004_api_keys.sql

@@ -0,0 +1,41 @@
+-- Migration: Create api_keys table for MCP authentication
+-- Run this in Supabase SQL Editor
+--
+-- API keys use the format ci_<hex> and are stored as SHA-256 hashes.
+-- The backend validates keys by hashing the incoming token and looking
+-- up the hash in this table.
+
+CREATE TABLE IF NOT EXISTS api_keys (
+  id uuid DEFAULT gen_random_uuid() PRIMARY KEY,
+  user_id uuid REFERENCES auth.users(id) ON DELETE CASCADE,
+  name text NOT NULL,
+  key_hash text NOT NULL UNIQUE,
+  tier text DEFAULT 'free',
+  active boolean DEFAULT true,
+  created_at timestamptz DEFAULT now(),
+  last_used_at timestamptz
+);
+
+-- Index for fast hash lookups during auth
+CREATE INDEX IF NOT EXISTS idx_api_keys_hash_active
+  ON api_keys (key_hash) WHERE active = true;
+
+-- Enable RLS
+ALTER TABLE api_keys ENABLE ROW LEVEL SECURITY;
+
+-- Users can only see their own keys
+CREATE POLICY "Users can view own keys"
+  ON api_keys FOR SELECT
+  USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can create own keys"
+  ON api_keys FOR INSERT
+  WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Users can deactivate own keys"
+  ON api_keys FOR UPDATE
+  USING (auth.uid() = user_id)
+  WITH CHECK (auth.uid() = user_id);
+
+-- Service role (backend) has full access via service_role key
+-- No explicit policy needed; service_role bypasses RLS