MedX MCP Server

# MCP Server API Documentation **Version:** 0.1.0 **Base URL:** `http://localhost:8000` (or your server URL) **API Type:** RESTful with Server-Sent Events (SSE) for streaming --- ## Table of Contents 1. [Authentication](#authentication) 2. [Endpoints](#endpoints) - [Health Checks](#health-checks) - [Manifest](#get-server-manifest) - [Execute Tool](#execute-tool) - [Stream Results](#stream-results) - [Cancel Call](#cancel-call) - [Cancel All Calls](#cancel-all-calls) 3. [Request/Response Examples](#requestresponse-examples) 4. [Error Handling](#error-handling) 5. [Best Practices](#best-practices) 6. [Rate Limits & Quotas](#rate-limits--quotas) --- ## Authentication All MCP endpoints (except health checks) require **Bearer Token** authentication. ### Header Format ``` Authorization: Bearer <your-token> ``` ### Getting Your Token The server token is configured via the `MCP_SERVER_TOKEN` environment variable. **Default (POC):** `super-secret-token` **Production:** Use a secure, randomly generated token. ### Example ```bash curl -H "Authorization: Bearer super-secret-token" \ http://localhost:8000/mcp/manifest ``` --- ## Endpoints ### Health Checks These endpoints do **not** require authentication. #### GET `/healthz` Liveness probe - checks if server is running. **Request:** ```bash curl http://localhost:8000/healthz ``` **Response:** ```json { "status": "ok" } ``` **Status Codes:** - `200 OK`: Server is alive --- #### GET `/readyz` Readiness probe - checks if server is ready to accept requests. **Request:** ```bash curl http://localhost:8000/readyz ``` **Response (Ready):** ```json { "ready": true } ``` **Response (Not Ready):** ```json { "ready": false, "reasons": ["missing OPENAI_API_KEY"] } ``` **Status Codes:** - `200 OK`: Server is ready - `503 Service Unavailable`: Server not ready (missing configuration) --- ### Get Server Manifest #### GET `/mcp/manifest` Get the list of available tools and their capabilities. **Authentication:** Required **Request:** ```bash curl -H "Authorization: Bearer super-secret-token" \ http://localhost:8000/mcp/manifest ``` **Response:** ```json { "server_name": "medx-mcp-server", "version": "0.1", "role": "AI-powered clinical agentic platform featuring our MedX-powered AI Agents and HealthOS, delivering advanced diagnostic support and personalized healthcare.", "description": "AI-powered clinical agentic platform featuring our MedX-powered AI Agents and HealthOS, delivering advanced diagnostic support and personalized healthcare.", "capabilities": [ "Advanced diagnostic support", "Personalized healthcare recommendations", "Clinical decision support", "AI-powered medical consultations" ], "tools": [ { "id": "openai_chat", "name": "openai_chat", "description": "Call OpenAI chat models (gpt-4o-mini default).", "inputs": { "messages": "array of {role, content}", "model": "string", "max_tokens": "int" } } ] } ``` **Status Codes:** - `200 OK`: Manifest returned successfully - `401 Unauthorized`: Missing or invalid token - `403 Forbidden`: Invalid authentication token --- ### Execute (Simplified) #### POST `/mcp/execute` Execute the default tool asynchronously. Returns immediately with a `call_id` that can be used to stream results. **Authentication:** Required **Request Body (Simplified):** ```json { "messages": [ {"role": "user", "content": "What are symptoms of anemia?"} ], "session_id": "patient-session-123", "request_id": "unique-request-id-456" } ``` **Request Fields (Simplified):** | Field | Type | Required | Description | |-------|------|----------|-------------| | `messages` | array | ✅ Yes | Array of message objects with `role` and `content` | | `session_id` | string | ❌ No | Session identifier for conversation tracking | | `request_id` | string | ❌ No | Unique request ID for idempotency (recommended) | | `metadata` | object | ❌ No | Additional metadata (stored but not processed) | Notes: - The server always uses tool `openai_chat` and model `gpt-4o-mini`. - If no `system` message is provided, the server injects a default Jivi AI system prompt. **Message Object Format:** ```json { "role": "system" | "user" | "assistant", "content": "Message text" } ``` **Request Example (Simplified):** ```bash curl -X POST \ -H "Authorization: Bearer super-secret-token" \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"role": "user", "content": "Hello, what is anemia?"} ], "session_id": "patient-123", "request_id": "req-456" }' \ http://localhost:8000/mcp/execute ``` **Response:** ```json { "call_id": "03431c1a-1522-451c-9a28-1926439ae1b4", "status": "started" } ``` **Response Fields:** | Field | Type | Description | |-------|------|-------------| | `call_id` | string | Unique identifier for this call (use for streaming) | | `status` | string | Current status: "started" | **Status Codes:** - `200 OK`: Call started successfully - `401 Unauthorized`: Missing or invalid token - `403 Forbidden`: Invalid authentication token - `422 Unprocessable Entity`: Invalid request format - `404 Not Found`: Tool not found **Idempotency:** If you send the same `request_id` again, the server will return the existing `call_id` and status without creating a duplicate call. This is useful for: - Handling network timeouts - Preventing duplicate API charges - Ensuring consistent responses **Example with Idempotency:** ```bash # First request POST /mcp/execute {"request_id": "req-123", ...} → Returns: {"call_id": "call-456", "status": "started"} # Retry with same request_id POST /mcp/execute {"request_id": "req-123", ...} → Returns: {"call_id": "call-456", "status": "finished"} # Same call! ``` --- ### Stream Results #### GET `/mcp/stream/{call_id}` Stream events for a call using Server-Sent Events (SSE). This endpoint provides real-time updates as the tool executes. **Authentication:** Required **Path Parameters:** - `call_id` (string, required): The call ID returned from `/mcp/execute` **Request:** ```bash curl -N -H "Authorization: Bearer super-secret-token" \ http://localhost:8000/mcp/stream/03431c1a-1522-451c-9a28-1926439ae1b4 ``` **Response Format (SSE):** ``` event: partial data: {"type": "partial", "text": "Anemia"} event: partial data: {"type": "partial", "text": " is"} event: partial data: {"type": "partial", "text": " a"} event: final data: {"type": "final", "text": "Anemia is a condition..."} ``` **Event Types:** | Event Type | Description | |------------|-------------| | `partial` | Incremental token/chunk of the response | | `final` | Complete response text (all partial chunks combined) | | `error` | Error occurred during execution | | `cancelled` | Call was cancelled | **Event Data Structure:** ```json { "type": "partial" | "final" | "error" | "cancelled", "text": "Token or full text", "message": "Error or cancellation message (for error/cancelled types)" } ``` **Streaming Behavior:** - Stream remains open until a `final`, `error`, or `cancelled` event is received - Timeout: 5 minutes (300 seconds) of inactivity - Multiple clients can stream the same `call_id` simultaneously - Tokens arrive in real-time as they are generated **JavaScript Example:** ```javascript const eventSource = new EventSource( 'http://localhost:8000/mcp/stream/03431c1a-1522-451c-9a28-1926439ae1b4', { headers: { 'Authorization': 'Bearer super-secret-token' } } ); let fullText = ''; eventSource.addEventListener('partial', (event) => { const data = JSON.parse(event.data); fullText += data.text; console.log('Partial:', data.text); }); eventSource.addEventListener('final', (event) => { const data = JSON.parse(event.data); fullText = data.text; // Complete text console.log('Complete:', fullText); eventSource.close(); }); eventSource.addEventListener('error', (event) => { console.error('Error:', event.data); eventSource.close(); }); ``` **Python Example:** ```python import requests import json url = "http://localhost:8000/mcp/stream/03431c1a-1522-451c-9a28-1926439ae1b4" headers = {"Authorization": "Bearer super-secret-token"} with requests.get(url, headers=headers, stream=True) as response: for line in response.iter_lines(): if line: # SSE format: "data: {...}" if line.startswith(b"data: "): data = json.loads(line[6:]) # Remove "data: " prefix if data["type"] == "partial": print(data["text"], end="", flush=True) elif data["type"] == "final": print(f"\n\nComplete: {data['text']}") break ``` **Status Codes:** - `200 OK`: Stream established - `401 Unauthorized`: Missing or invalid token - `403 Forbidden`: Invalid authentication token - `404 Not Found`: Call ID not found --- ### Cancel Call #### POST `/mcp/cancel/{call_id}` Cancel a running or pending call. **Authentication:** Required **Path Parameters:** - `call_id` (string, required): The call ID to cancel **Request:** ```bash curl -X POST \ -H "Authorization: Bearer super-secret-token" \ http://localhost:8000/mcp/cancel/03431c1a-1522-451c-9a28-1926439ae1b4 ``` **Response:** ```json { "status": "cancelled" } ``` **Behavior:** - Marks call as cancelled in registry - Sends cancellation signal to background task - Pushes `cancelled` event to stream queue - Records cancellation in session buffer (if session_id provided) **Status Codes:** - `200 OK`: Cancellation requested - `401 Unauthorized`: Missing or invalid token - `403 Forbidden`: Invalid authentication token - `404 Not Found`: Call ID not found --- ### Cancel All Calls #### POST `/mcp/cancel_all` Cancel all active calls. Useful for emergency shutdowns or cleanup. **Authentication:** Required **Request:** ```bash curl -X POST \ -H "Authorization: Bearer super-secret-token" \ http://localhost:8000/mcp/cancel_all ``` **Response:** ```json { "status": "cancelled", "count": 3, "call_ids": [ "call-123", "call-456", "call-789" ] } ``` **Response Fields:** | Field | Type | Description | |-------|------|-------------| | `status` | string | Always "cancelled" | | `count` | integer | Number of calls cancelled | | `call_ids` | array | List of cancelled call IDs | **Status Codes:** - `200 OK`: Cancellation completed - `401 Unauthorized`: Missing or invalid token - `403 Forbidden`: Invalid authentication token --- ## Request/Response Examples ### Complete Flow: Medical Query #### Step 1: Execute Tool ```bash curl -X POST \ -H "Authorization: Bearer super-secret-token" \ -H "Content-Type: application/json" \ -d '{ "tool": "openai_chat", "input": { "messages": [ { "role": "system", "content": "You are a careful medical assistant. Provide general information only." }, { "role": "user", "content": "What are common symptoms of iron deficiency anemia?" } ], "model": "gpt-4o-mini", "max_tokens": 512 }, "session_id": "patient-conversation-1", "request_id": "medical-query-001" }' \ http://localhost:8000/mcp/execute ``` **Response:** ```json { "call_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "started" } ``` #### Step 2: Stream Results ```bash curl -N -H "Authorization: Bearer super-secret-token" \ http://localhost:8000/mcp/stream/a1b2c3d4-e5f6-7890-abcd-ef1234567890 ``` **Stream Output:** ``` event: partial data: {"type": "partial", "text": "Common"} event: partial data: {"type": "partial", "text": " symptoms"} event: partial data: {"type": "partial", "text": " of"} ... (many more partial events) ... event: final data: {"type": "final", "text": "Common symptoms of iron deficiency anemia include:\n\n1. Fatigue\n2. Weakness\n3. Pale skin\n..."} ``` #### Step 3: Conversational Follow-up (Same Session) ```bash curl -X POST \ -H "Authorization: Bearer super-secret-token" \ -H "Content-Type: application/json" \ -d '{ "tool": "openai_chat", "input": { "messages": [ {"role": "system", "content": "You are a careful medical assistant."}, {"role": "user", "content": "What are common symptoms of iron deficiency anemia?"}, {"role": "assistant", "content": "Common symptoms of iron deficiency anemia include:\n\n1. Fatigue\n2. Weakness\n3. Pale skin\n..."}, {"role": "user", "content": "What tests should I ask my doctor about?"} ], "max_tokens": 400 }, "session_id": "patient-conversation-1", "request_id": "medical-query-002" }' \ http://localhost:8000/mcp/execute ``` --- ## Error Handling ### Error Response Format All errors follow a consistent format: ```json { "error": { "message": "Error description", "error_code": "ERROR_CODE", "type": "ExceptionClassName" } } ``` ### Error Codes | Error Code | Status Code | Description | |------------|-------------|-------------| | `AUTH_ERROR` | 401 | Missing or invalid authentication | | `AUTHZ_ERROR` | 403 | Invalid token | | `TOOL_NOT_FOUND` | 404 | Requested tool does not exist | | `CALL_NOT_FOUND` | 404 | Call ID not found | | `VALIDATION_ERROR` | 422 | Invalid request format | | `OPENAI_ERROR` | 502 | OpenAI API error | ### Common Errors #### 401 Unauthorized ```json { "error": { "message": "Missing or malformed Authorization header", "error_code": "AUTH_ERROR", "type": "AuthenticationError" } } ``` **Solution:** Include `Authorization: Bearer <token>` header. #### 404 Tool Not Found ```json { "error": { "message": "Tool 'invalid_tool' not found", "error_code": "TOOL_NOT_FOUND", "type": "ToolNotFoundError" } } ``` **Solution:** Check `/mcp/manifest` for available tools. #### 404 Call Not Found ```json { "error": { "message": "Call 'invalid-call-id' not found", "error_code": "CALL_NOT_FOUND", "type": "CallNotFoundError" } } ``` **Solution:** Use a valid `call_id` from `/mcp/execute` response. #### Stream Errors During streaming, errors are sent as SSE events: ``` event: error data: {"type": "error", "message": "OpenAI API error: Rate limit exceeded"} ``` --- ## Best Practices ### 1. Always Use `request_id` for Idempotency ```json { "request_id": "unique-client-request-id-12345" } ``` **Benefits:** - Prevents duplicate charges on retries - Ensures consistent responses - Handles network failures gracefully **Generation Tips:** - Use UUID: `uuid.uuid4().hex` - Include timestamp: `f"{timestamp}-{unique-id}"` - Include session: `f"{session_id}-{request_number}"` ### 2. Use `session_id` for Conversation Tracking ```json { "session_id": "user-123-conversation-1" } ``` **Benefits:** - Track conversation history - Enable context-aware responses - Support multi-turn conversations ### 3. Handle Streaming Properly **Do:** - Keep connection open until `final` or `error` event - Accumulate `partial` events to build complete text - Handle timeouts gracefully - Close connection after `final` event **Don't:** - Close connection on first `partial` event - Ignore `final` event (it contains complete text) - Assume streaming will never timeout ### 4. Error Handling Strategy ```python try: # Execute call response = requests.post(execute_url, json=payload, headers=auth_headers) response.raise_for_status() call_id = response.json()["call_id"] # Stream results stream_response = requests.get(stream_url.format(call_id=call_id), headers=auth_headers, stream=True) for line in stream_response.iter_lines(): if line.startswith(b"data: "): data = json.loads(line[6:]) if data["type"] == "error": raise Exception(f"Stream error: {data['message']}") elif data["type"] == "final": return data["text"] except requests.exceptions.HTTPError as e: if e.response.status_code == 401: # Handle authentication error elif e.response.status_code == 404: # Handle not found error ``` ### 5. Implement Retry Logic ```python import time from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def create_session_with_retries(): session = requests.Session() retry_strategy = Retry( total=3, backoff_factor=1, status_forcelist=[429, 500, 502, 503, 504] ) adapter = HTTPAdapter(max_retries=retry_strategy) session.mount("http://", adapter) session.mount("https://", adapter) return session ``` **Important:** Use same `request_id` on retries for idempotency! ### 6. Monitor Health Endpoints Before making API calls, check server health: ```python health_response = requests.get(f"{base_url}/healthz") ready_response = requests.get(f"{base_url}/readyz") if ready_response.json().get("ready"): # Server is ready, proceed with requests else: # Server not ready, handle accordingly ``` ### 7. Set Appropriate Timeouts ```python # For execute endpoint (should return quickly) execute_response = requests.post( execute_url, json=payload, headers=auth_headers, timeout=10 # 10 seconds ) # For stream endpoint (long-running) stream_response = requests.get( stream_url, headers=auth_headers, stream=True, timeout=300 # 5 minutes (matches server timeout) ) ``` --- ## Rate Limits & Quotas **Current Implementation:** - No rate limiting enforced (POC) - Server processes requests concurrently - Limited by OpenAI API rate limits **Production Considerations:** - Implement per-client rate limiting - Set quotas for API usage - Monitor and log all requests - Consider request queuing for high load --- ## Complete Client Implementation Example ### Python Client ```python import requests import json import uuid from typing import Optional, Iterator class MCPClient: def __init__(self, base_url: str, token: str): self.base_url = base_url.rstrip('/') self.token = token self.headers = { "Authorization": f"Bearer {token}", "Content-Type": "application/json" } def execute( self, tool: str, messages: list, session_id: Optional[str] = None, request_id: Optional[str] = None, model: Optional[str] = None, max_tokens: int = 512 ) -> dict: """Execute a tool and return call_id.""" payload = { "tool": tool, "input": { "messages": messages, "max_tokens": max_tokens } } if model: payload["input"]["model"] = model if session_id: payload["session_id"] = session_id if request_id: payload["request_id"] = request_id else: payload["request_id"] = str(uuid.uuid4()) response = requests.post( f"{self.base_url}/mcp/execute", json=payload, headers=self.headers, timeout=10 ) response.raise_for_status() return response.json() def stream(self, call_id: str) -> Iterator[dict]: """Stream events for a call.""" url = f"{self.base_url}/mcp/stream/{call_id}" response = requests.get(url, headers=self.headers, stream=True, timeout=300) response.raise_for_status() for line in response.iter_lines(): if line.startswith(b"data: "): yield json.loads(line[6:]) elif line.startswith(b"event: "): event_type = line[7:].decode() # Event type is in the line, next line will have data def execute_and_stream( self, messages: list, session_id: Optional[str] = None, **kwargs ) -> Iterator[str]: """Execute and stream in one call.""" result = self.execute("openai_chat", messages, session_id, **kwargs) call_id = result["call_id"] full_text = "" for event in self.stream(call_id): if event["type"] == "partial": full_text += event["text"] yield event["text"] elif event["type"] == "final": yield event["text"] break elif event["type"] == "error": raise Exception(f"Error: {event.get('message', 'Unknown error')}") def cancel(self, call_id: str) -> dict: """Cancel a call.""" response = requests.post( f"{self.base_url}/mcp/cancel/{call_id}", headers=self.headers, timeout=5 ) response.raise_for_status() return response.json() def health_check(self) -> dict: """Check server health.""" response = requests.get(f"{self.base_url}/healthz", timeout=5) response.raise_for_status() return response.json() def ready_check(self) -> dict: """Check server readiness.""" response = requests.get(f"{self.base_url}/readyz", timeout=5) return response.json() # Usage Example if __name__ == "__main__": client = MCPClient("http://localhost:8000", "super-secret-token") # Check server print("Health:", client.health_check()) print("Ready:", client.ready_check()) # Execute and stream messages = [ {"role": "user", "content": "What is anemia?"} ] print("\nStreaming response:") for chunk in client.execute_and_stream(messages, session_id="demo-1"): print(chunk, end="", flush=True) print("\n") ``` ### JavaScript/TypeScript Client ```typescript class MCPClient { constructor(private baseUrl: string, private token: string) {} async execute( tool: string, input: any, sessionId?: string, requestId?: string ): Promise<{ call_id: string; status: string }> { const response = await fetch(`${this.baseUrl}/mcp/execute`, { method: 'POST', headers: { 'Authorization': `Bearer ${this.token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ tool, input, session_id: sessionId, request_id: requestId || crypto.randomUUID() }) }); if (!response.ok) { throw new Error(`HTTP ${response.status}: ${await response.text()}`); } return response.json(); } stream(callId: string): ReadableStream<string> { const url = `${this.baseUrl}/mcp/stream/${callId}`; return new ReadableStream({ async start(controller) { const eventSource = new EventSource(url, { withCredentials: false }); // Note: Browser EventSource doesn't support custom headers // You may need to pass token as query param or use fetch API eventSource.addEventListener('partial', (event: any) => { const data = JSON.parse(event.data); controller.enqueue(data.text); }); eventSource.addEventListener('final', (event: any) => { const data = JSON.parse(event.data); controller.enqueue(data.text); controller.close(); eventSource.close(); }); eventSource.addEventListener('error', (event: any) => { controller.error(new Error(event.data)); eventSource.close(); }); } }); } async cancel(callId: string): Promise<void> { await fetch(`${this.baseUrl}/mcp/cancel/${callId}`, { method: 'POST', headers: { 'Authorization': `Bearer ${this.token}` } }); } } // Usage const client = new MCPClient('http://localhost:8000', 'super-secret-token'); const result = await client.execute('openai_chat', { messages: [{ role: 'user', content: 'Hello!' }] }); const stream = client.stream(result.call_id); const reader = stream.getReader(); while (true) { const { done, value } = await reader.read(); if (done) break; process.stdout.write(value); } ``` --- ## Support & Troubleshooting ### Common Issues **1. "Missing auth" error** - Ensure `Authorization` header is included - Check token is correct - Verify header format: `Bearer <token>` (space required) **2. Stream times out** - Check network connection - Verify server is running - Ensure call_id is valid and call hasn't completed **3. Call not found** - Verify call_id is from recent execute request - Check if call completed (calls may be cleaned up) - Ensure you're using correct call_id format **4. Slow responses** - Normal for long AI generations - Check OpenAI API status - Consider using smaller `max_tokens` for faster responses ### Debugging Tips 1. **Enable verbose logging** (client-side): ```python import logging logging.basicConfig(level=logging.DEBUG) ``` 2. **Check server logs**: - Logs are written to `logs/server.log` - Monitor for errors or warnings 3. **Test with curl** first: ```bash # Simple test curl -H "Authorization: Bearer token" \ http://localhost:8000/mcp/manifest ``` 4. **Validate request format**: - Use JSON validator - Check message format matches specification - Ensure all required fields are present --- ## Changelog ### Version 0.1.0 - Initial release - Support for `openai_chat` tool - Streaming via SSE - Idempotency support - Session tracking - Cancellation support --- ## License & Terms This API documentation is provided for the MCP Server POC. For production use, consult your organization's API terms and conditions.