Proxy Management API Documentation

This document describes the REST API endpoints for managing and monitoring multiple MCP and LLM proxy instances through the Unified AI Gateway.

📘 Documentation Scope: This guide covers the 20 most commonly used proxy management endpoints for getting started with command-line and scripting workflows. Complete API reference with all 150+ endpoints will be added in future releases.

Proxy API Overview

The Unified AI Gateway provides comprehensive proxy management capabilities through a centralized API. You can create, configure, and manage multiple proxy instances (both MCP and LLM), assign security policies, monitor traffic, and retrieve detailed statistics.

Key Features:

Multi-proxy management with individual configurations
Real-time monitoring and statistics
Security policy assignment per proxy
MCP tool discovery and management
LLM token usage tracking
Request logging and analytics
WebSocket real-time notifications

Proxy API Base URL

The unified API server runs on port 8080 by default. All proxy management endpoints are available at:

http://localhost:8080/api/v1

Proxy API Authentication

All proxy management endpoints require authentication. The API supports multiple authentication methods for command-line and scripting use.

Authentication Methods

1. JWT Token (Admin Users)

Most common method for administrative access:

bash

# Step 1: Login to get JWT token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"yourpassword"}' | jq -r '.data.token'

# Step 2: Save token for reuse
export JWT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Step 3: Use in all API requests
curl -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/

Token Details:

Default expiry: 24 hours
Refresh via POST /api/v1/auth/refresh
See Authentication Guide for complete details

2. OAuth Session Token

For users authenticated via OAuth providers (GitHub, Google, etc.):

bash

# After OAuth login via web UI, extract session token
export JWT_TOKEN="<session-token-from-oauth-login>"

# Use identically to JWT tokens
curl -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/

Note: OAuth session tokens work interchangeably with admin JWT tokens in all endpoints.

3. API Key (Programmatic Access)

For automation and service accounts:

bash

# Use X-API-Key header instead of Authorization
curl -H "X-API-Key: YOUR_API_KEY" \
  http://localhost:8080/api/v1/proxies/

Note: API keys are scoped to user groups with specific permissions and rate limits.

Role-Based Access Control

Endpoints require different roles:

Viewer: Read-only access (list proxies, view status, logs, statistics)
Operator: Can start/stop proxies (in addition to viewer permissions)
Admin: Full access (create, update, delete proxies and policies)

Each endpoint documents its required role below.

Quick Start Example

bash

# 1. Login and save token
export JWT_TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.data.token')

# 2. List all proxies
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/ | jq

# 3. Get proxy status
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/1/status | jq

See Also:

Authentication Guide - Complete authentication reference
OAuth API Reference - OAuth provider setup
API Examples - More usage examples

Endpoint Categories

Endpoint Overview

Health Check: System health and status
Dashboard: Unified metrics and overview

Configuration Endpoints

List Proxies: Get all proxy configurations with filtering
Create Proxy: Create new proxy configuration
Get Proxy: Retrieve specific proxy configuration
Update Proxy: Modify proxy configuration
Delete Proxy: Remove proxy configuration

Lifecycle Endpoints

Start Proxy: Start proxy instance
Stop Proxy: Stop proxy instance
Restart Proxy: Restart proxy instance
Get Status: Get proxy runtime status
Get All Status: Get status of all proxies

Monitoring Endpoints

Get Logs: Retrieve request logs
Get Statistics: Get proxy metrics and statistics
Get Token Usage: LLM token consumption (LLM proxies only)

Policy Endpoints

Get Policies: Get assigned and available policies
Assign Policies: Assign multiple policies to proxy
Add Policy: Add single policy to proxy
Remove Policy: Remove policy from proxy

MCP Tool Management (MCP Proxies Only)

List Tools: Get all MCP tools
Discover Tools: Discover tools from MCP server
Update Tool: Enable/disable specific tool
Bulk Update Tools: Update multiple tools at once
Get Tool Stats: Tool usage statistics

Proxy Core Endpoints

System Health Check

Check the overall health and status of the unified API server.

Endpoint: GET /api/v1/health

Response Format:

json

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-01-22T12:34:56.789Z",
    "version": "1.0.0"
  }
}

Authentication: None required (public endpoint)

Example Request:

bash

curl -s http://localhost:8080/api/v1/health | jq

Response Codes:

200 OK: Service is healthy
500 Internal Server Error: Service is experiencing issues

Proxy Configuration Management

List All Proxy Configurations

Retrieve all proxy configurations with optional filtering.

Endpoint: GET /api/v1/proxies/

Authentication: Required (viewer role or higher)

Query Parameters:**

type (optional): Filter by proxy type (mcp or llm)
enabled (optional): Filter by enabled status (true or false)
search (optional): Search by name or description

Response Format:

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "production-mcp",
      "type": "mcp",
      "transport": "http",
      "description": "Production MCP server proxy",
      "target": "http://localhost:3000",
      "port": 8081,
      "enabled": true,
      "auto_start": false,
      "tags": ["production", "main"],
      "policies": [
        {
          "name": "critical-security",
          "exists": true,
          "active": true,
          "description": "Critical security patterns",
          "severity": "Critical"
        }
      ],
      "policy_count": 2,
      "active_policy_count": 2,
      "created_at": "2025-01-20T10:00:00Z",
      "updated_at": "2025-01-22T12:00:00Z"
    }
  ]
}

Example Requests:

bash

# Get all proxies
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/ | jq

# Filter by type
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/?type=mcp" | jq

# Filter enabled proxies
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/?enabled=true" | jq

# Search proxies
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/?search=production" | jq

Create Proxy Configuration

Create a new proxy configuration.

Endpoint: POST /api/v1/proxies/

Authentication: Required (admin role)

Request Body:**

json

{
  "name": "new-mcp-proxy",
  "type": "mcp",
  "transport": "http",
  "description": "New MCP server proxy",
  "target": "http://localhost:3000",
  "port": 8081,
  "enabled": true,
  "auto_start": false,
  "policy_names": ["critical-security", "standard-security"],
  "tags": ["development", "testing"]
}

Field Descriptions:

name (required, string): Unique proxy name
type (required, string): Proxy type (mcp or llm)
transport (optional, string): Transport protocol (http, websocket, sse). Default: http
description (optional, string): Proxy description
target (required, string): Target server URL
port (required, integer): Local proxy port
enabled (optional, boolean): Enable/disable proxy. Default: true
auto_start (optional, boolean): Auto-start on server startup. Default: false
policy_names (optional, array): Security policy names to assign
tags (optional, array): Tags for categorization

Example Request:

bash

curl -s -X POST http://localhost:8080/api/v1/proxies/ \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-mcp",
    "type": "mcp",
    "transport": "http",
    "target": "http://localhost:3000",
    "port": 8081,
    "enabled": true,
    "policy_names": ["critical-security"]
  }' | jq

Response:

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "production-mcp",
    ...
  },
  "message": "Proxy configuration created successfully"
}

Get Specific Proxy Configuration

Retrieve a specific proxy configuration by ID.

Endpoint: GET /api/v1/proxies/{id}

Authentication: Required (viewer role or higher)

Path Parameters:

id (required, integer): Proxy configuration ID

Example Request:

bash

curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/1 | jq

Update Proxy Configuration

Update an existing proxy configuration.

Endpoint: PUT /api/v1/proxies/{id}

Authentication: Required (admin role)

Path Parameters:**

id (required, integer): Proxy configuration ID

Request Body: Partial or complete configuration object

Example Request:

bash

curl -s -X PUT http://localhost:8080/api/v1/proxies/1 \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "auto_start": true,
    "description": "Updated description"
  }' | jq

Delete Proxy Configuration

Delete a proxy configuration. Proxy must be stopped before deletion.

Endpoint: DELETE /api/v1/proxies/{id}

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID

Example Request:

bash

curl -s -X DELETE http://localhost:8080/api/v1/proxies/1 \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

Proxy Lifecycle Control API

Start Proxy Instance

Start a proxy instance to begin proxying traffic.

Endpoint: POST /api/v1/proxies/{id}/start

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID

Example Request:

bash

curl -s -X POST http://localhost:8080/api/v1/proxies/1/start \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

Response:

json

{
  "success": true,
  "message": "Proxy started successfully"
}

Stop Proxy Instance

Stop a running proxy instance.

Endpoint: POST /api/v1/proxies/{id}/stop

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID

Example Request:

bash

curl -s -X POST http://localhost:8080/api/v1/proxies/1/stop \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

Restart Proxy Instance

Restart a proxy instance (stop then start).

Endpoint: POST /api/v1/proxies/{id}/restart

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID

Example Request:

bash

curl -s -X POST http://localhost:8080/api/v1/proxies/1/restart \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

Get Proxy Status

Get the runtime status of a specific proxy instance.

Endpoint: GET /api/v1/proxies/{id}/status

Authentication: Required (viewer role or higher)

Path Parameters:**

id (required, integer): Proxy configuration ID

Response Format:

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "production-mcp",
    "type": "mcp",
    "running": true,
    "port": 8081,
    "target": "http://localhost:3000",
    "start_time": "2025-01-22T10:00:00Z",
    "uptime": "2h 15m 30s",
    "requests_processed": 1523,
    "errors": 3
  }
}

Example Request:

bash

curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/1/status | jq

Get All Proxy Statuses

Get runtime status for all proxy instances.

Endpoint: GET /api/v1/proxies/status

Authentication: Required (viewer role or higher)

Response Format:**

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "production-mcp",
      "type": "mcp",
      "running": true,
      "port": 8081
    },
    {
      "id": 2,
      "name": "openai-llm",
      "type": "llm",
      "running": false,
      "port": 8082
    }
  ]
}

Example Request:

bash

curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/status | jq

Monitoring & Analytics

Get Proxy Logs

Retrieve request logs for a specific proxy.

Endpoint: GET /api/v1/proxies/{id}/logs

Authentication: Required (viewer role or higher)

Path Parameters:**

id (required, integer): Proxy configuration ID

Query Parameters:

limit (optional, integer): Maximum number of logs to return (default: 100)

Response Format:

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "proxy_config_id": 1,
      "timestamp": "2025-01-22T12:30:00Z",
      "method": "POST",
      "path": "/mcp/tools/call",
      "status_code": 200,
      "duration_ms": 45,
      "request_size": 1024,
      "response_size": 2048,
      "client_ip": "192.168.1.100",
      "risk_level": "Medium"
    }
  ]
}

Example Request:

bash

# Get last 100 logs (default)
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/1/logs" | jq

# Get last 50 logs
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/1/logs?limit=50" | jq

Get Proxy Statistics

Get aggregate statistics for a specific proxy.

Endpoint: GET /api/v1/proxies/{id}/stats

Authentication: Required (viewer role or higher)

Path Parameters:**

id (required, integer): Proxy configuration ID

Query Parameters:

hours (optional, integer): Time range in hours (default: 24)

Response Format:

json

{
  "success": true,
  "data": {
    "proxy_id": 1,
    "time_range_hours": 24,
    "total_requests": 1523,
    "successful_requests": 1520,
    "failed_requests": 3,
    "avg_response_time_ms": 45.2,
    "total_data_transferred": 15728640,
    "alerts_triggered": 5,
    "top_endpoints": [
      {
        "path": "/mcp/tools/call",
        "count": 850
      },
      {
        "path": "/mcp/tools/list",
        "count": 673
      }
    ]
  }
}

Example Request:

bash

# Get stats for last 24 hours (default)
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/1/stats" | jq

# Get stats for last week
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/1/stats?hours=168" | jq

Get Token Usage (LLM Proxies Only)

Retrieve token consumption and cost data for LLM proxies.

Endpoint: GET /api/v1/proxies/{id}/tokens

Authentication: Required (viewer role or higher)

Path Parameters:**

id (required, integer): Proxy configuration ID (must be LLM type)

Query Parameters:

days (optional, integer): Time range in days (default: 30)

Response Format:

json

{
  "success": true,
  "data": {
    "proxy_id": 2,
    "proxy_name": "openai-gpt4",
    "period_days": 30,
    "totals": {
      "total_tokens": 1500000,
      "total_cost": 45.50,
      "request_count": 523
    },
    "recent_usage": [
      {
        "id": 1,
        "timestamp": "2025-01-22T12:00:00Z",
        "model": "gpt-4",
        "input_tokens": 1500,
        "output_tokens": 500,
        "total_tokens": 2000,
        "cost": 0.12
      }
    ],
    "records_count": 100
  }
}

Example Request:

bash

# Get token usage for last 30 days (default)
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/2/tokens" | jq

# Get token usage for last 7 days
curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  "http://localhost:8080/api/v1/proxies/2/tokens?days=7" | jq

Policy Management API

Get Proxy Policies

Get assigned and available policies for a specific proxy.

Endpoint: GET /api/v1/proxies/{id}/policies

Authentication: Required (viewer role or higher)

Path Parameters:**

id (required, integer): Proxy configuration ID

Response Format:

json

{
  "success": true,
  "data": {
    "assigned_policies": [
      "critical-security",
      "mcp-advanced-security"
    ],
    "available_policies": [
      {
        "id": "critical-security",
        "name": "critical-security",
        "description": "Critical security patterns",
        "version": "1.0",
        "severity": "Critical",
        "policy_type": "mcp",
        "assigned": true,
        "active": true
      },
      {
        "id": "standard-security",
        "name": "standard-security",
        "description": "Standard security checks",
        "version": "1.0",
        "severity": "Medium",
        "policy_type": "both",
        "assigned": false,
        "active": true
      }
    ]
  }
}

Example Request:

bash

curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/1/policies | jq

Assign Multiple Policies

Assign multiple policies to a proxy (replaces existing assignments).

Endpoint: POST /api/v1/proxies/{id}/policies

Authentication: Required (admin role)

Path Parameters:**

id (required, integer): Proxy configuration ID

Request Body:

json

{
  "policy_names": [
    "critical-security",
    "mcp-advanced-security",
    "custom-rules"
  ]
}

Example Request:

bash

curl -s -X POST http://localhost:8080/api/v1/proxies/1/policies \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_names": ["critical-security", "mcp-advanced-security"]
  }' | jq

Add Single Policy

Add a single policy to a proxy without removing existing policies.

Endpoint: PUT /api/v1/proxies/{id}/policies/{policyName}

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID
policyName (required, string): Policy name to add

Example Request:

bash

curl -s -X PUT http://localhost:8080/api/v1/proxies/1/policies/standard-security \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

Remove Policy

Remove a policy from a proxy.

Endpoint: DELETE /api/v1/proxies/{id}/policies/{policyName}

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID
policyName (required, string): Policy name to remove

Example Request:

bash

curl -s -X DELETE http://localhost:8080/api/v1/proxies/1/policies/standard-security \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

MCP Tool Management API

Note: These endpoints only work with MCP-type proxies.

List MCP Tools

List all MCP tools configured for a proxy.

Endpoint: GET /api/v1/proxies/{id}/tools

Authentication: Required (viewer role or higher)

Path Parameters:**

id (required, integer): Proxy configuration ID (must be MCP type)

Response Format:

json

{
  "success": true,
  "data": {
    "proxy_id": 1,
    "tools": [
      {
        "id": 1,
        "name": "read_file",
        "description": "Read file contents",
        "enabled": true,
        "discovered_at": "2025-01-22T10:00:00Z"
      },
      {
        "id": 2,
        "name": "execute_command",
        "description": "Execute system command",
        "enabled": false,
        "discovered_at": "2025-01-22T10:00:00Z"
      }
    ],
    "count": 2
  }
}

Example Request:

bash

curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/1/tools | jq

Discover MCP Tools

Discover tools from the MCP server and save them to the database.

🔒 Security Behavior: Newly discovered tools are disabled by default for security. Each tool must be explicitly enabled by an administrator before it can be used. This fail-closed approach prevents unauthorized tool execution.

Endpoint: POST /api/v1/proxies/{id}/tools/discover

Authentication: Required (admin role)

Path Parameters:**

id (required, integer): Proxy configuration ID (must be MCP type)

Response Format:

json

{
  "success": true,
  "data": {
    "proxy_id": 1,
    "tools": [...],
    "discovered": 5,
    "message": "Successfully discovered 5 tools (all disabled by default)"
  }
}

Important: After discovery, tools will have "enabled": false. Use the Update Tool Status endpoint to enable specific tools.

Example Request:

bash

curl -s -X POST http://localhost:8080/api/v1/proxies/1/tools/discover \
  -H "Authorization: Bearer $JWT_TOKEN" | jq

Update Tool Status

Enable or disable a specific MCP tool.

Endpoint: PUT /api/v1/proxies/{id}/tools/{toolName}

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID
toolName (required, string): Tool name to update

Request Body:

json

{
  "enabled": false
}

Example Request:

bash

# Disable a tool
curl -s -X PUT http://localhost:8080/api/v1/proxies/1/tools/execute_command \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}' | jq

# Enable a tool
curl -s -X PUT http://localhost:8080/api/v1/proxies/1/tools/read_file \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' | jq

Bulk Update Tools

Update enabled status for multiple tools at once.

Endpoint: PUT /api/v1/proxies/{id}/tools/bulk

Authentication: Required (admin role)

Path Parameters:

id (required, integer): Proxy configuration ID

Request Body:

json

{
  "tool_names": ["read_file", "write_file", "execute_command"],
  "enabled": false
}

Example Request:

bash

# Disable multiple tools
curl -s -X PUT http://localhost:8080/api/v1/proxies/1/tools/bulk \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_names": ["execute_command", "system_call"],
    "enabled": false
  }' | jq

Get Tool Statistics

Get usage statistics for MCP tools.

Endpoint: GET /api/v1/proxies/{id}/tools/stats

Authentication: Required (viewer role or higher)

Path Parameters:**

id (required, integer): Proxy configuration ID

Response Format:

json

{
  "success": true,
  "data": {
    "proxy_id": 1,
    "stats": {
      "total_tools": 5,
      "enabled_tools": 3,
      "disabled_tools": 2,
      "most_used_tools": [
        {
          "name": "read_file",
          "usage_count": 523
        }
      ]
    }
  }
}

Example Request:

bash

curl -s -H "Authorization: Bearer $JWT_TOKEN" \
  http://localhost:8080/api/v1/proxies/1/tools/stats | jq

Proxy API Error Handling

All endpoints return JSON responses with appropriate HTTP status codes. Error responses follow this format:

json

{
  "success": false,
  "error": "Error description message",
  "message": "Optional user-friendly message"
}

Common HTTP Status Codes:

200 OK: Request successful
400 Bad Request: Invalid request parameters or body
404 Not Found: Proxy configuration or resource not found
500 Internal Server Error: Server-side error

Proxy API Rate Limiting

Currently, no rate limiting is implemented on monitoring endpoints. In production, consider implementing rate limiting to prevent abuse.

WebSocket Endpoint

The unified API server provides a WebSocket endpoint for real-time notifications about proxy status, alerts, and system events.

Endpoint: WS /ws

Authentication: Required (JWT token via query parameter)

Connection:

javascript

// Include JWT token in WebSocket URL
const token = 'YOUR_JWT_TOKEN';
const ws = new WebSocket(`ws://localhost:8080/ws?token=${token}`);

ws.onopen = () => {
  console.log('Connected to unified API WebSocket');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  switch (data.type) {
    case 'alert':
      console.log('New Alert:', data.payload);
      break;
    case 'proxy_status':
      console.log('Proxy Status Update:', data.payload);
      break;
    case 'stats_update':
      console.log('Stats Update:', data.payload);
      break;
  }
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('WebSocket connection closed');
};

Message Types:

alert: New security alert generated
proxy_status: Proxy instance status change (started, stopped, error)
stats_update: Real-time statistics update
system_event: System-level event notification

Proxy API Security Considerations

Network Security: Ensure API endpoints are only accessible from trusted networks
Authentication: Implement authentication for production deployments (currently not implemented)
Data Sensitivity: Log data and statistics may contain sensitive information - handle appropriately
HTTPS: Use HTTPS/WSS in production environments
Access Logs: Monitor API access for security audit purposes
Policy Validation: Always validate and test security policies before assigning to production proxies
Tool Management: Carefully review MCP tools before enabling them - disable dangerous tools by default

Proxy Integration Examples

Complete Proxy Setup

bash

#!/bin/bash
# Create and configure a new MCP proxy

# 1. Create proxy
PROXY_JSON=$(curl -s -X POST http://localhost:8080/api/v1/proxies/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-mcp-01",
    "type": "mcp",
    "target": "http://localhost:3000",
    "port": 8081,
    "enabled": true,
    "tags": ["production", "critical"]
  }')

PROXY_ID=$(echo $PROXY_JSON | jq -r '.data.id')
echo "Created proxy with ID: $PROXY_ID"

# 2. Assign security policies
curl -s -X POST http://localhost:8080/api/v1/proxies/$PROXY_ID/policies \
  -H "Content-Type: application/json" \
  -d '{"policy_names": ["critical-security", "mcp-advanced-security"]}' | jq

# 3. Start the proxy
curl -s -X POST http://localhost:8080/api/v1/proxies/$PROXY_ID/start | jq

# 4. Verify status
curl -s http://localhost:8080/api/v1/proxies/$PROXY_ID/status | jq

Monitor Proxy Health

python

import requests
import time

def monitor_proxy(proxy_id, check_interval=30):
    """Monitor proxy health and log issues"""
    api_base = "http://localhost:8080/api/v1"

    while True:
        # Get proxy status
        status_resp = requests.get(f"{api_base}/proxies/{proxy_id}/status")
        status = status_resp.json()

        if not status['data']['running']:
            print(f"⚠️  Proxy {proxy_id} is not running!")
            # Attempt restart
            requests.post(f"{api_base}/proxies/{proxy_id}/start")

        # Check for errors in recent logs
        logs_resp = requests.get(f"{api_base}/proxies/{proxy_id}/logs?limit=10")
        logs = logs_resp.json()

        errors = [log for log in logs['data'] if log['status_code'] >= 400]
        if errors:
            print(f"⚠️  Found {len(errors)} errors in recent logs")

        time.sleep(check_interval)

# Usage
monitor_proxy(1, check_interval=60)

Proxy SIEM Integration

python

import requests
import time

def forward_alerts_to_siem(siem_endpoint, api_base="http://localhost:8080/api/v1"):
    """Poll for new alerts and forward to SIEM"""
    last_check = time.time() - 3600  # Start with last hour

    while True:
        # Get recent alerts
        time_range = "1h"  # Last hour
        response = requests.get(
            f"{api_base}/system/alerts",
            params={
                'time_range': time_range,
                'status': 'open'
            }
        )

        if response.status_code == 200:
            data = response.json()
            alerts = data.get('data', {}).get('alerts', [])

            for alert in alerts:
                # Transform and forward to SIEM
                siem_event = {
                    'event_type': 'security_alert',
                    'severity': alert['severity'],
                    'source': 'ai-security-gateway',
                    'alert_data': alert
                }
                requests.post(siem_endpoint, json=siem_event)
                print(f"Forwarded alert {alert['id']} to SIEM")

        time.sleep(30)  # Poll every 30 seconds

# Usage
forward_alerts_to_siem('https://siem.company.com/webhook')

Real-Time Dashboard

javascript

// React component for real-time proxy monitoring
import React, { useEffect, useState } from 'react';

function ProxyMonitor({ proxyId }) {
  const [status, setStatus] = useState(null);
  const [stats, setStats] = useState(null);

  useEffect(() => {
    // Poll for updates
    const interval = setInterval(async () => {
      // Get status
      const statusResp = await fetch(
        `http://localhost:8080/api/v1/proxies/${proxyId}/status`
      );
      const statusData = await statusResp.json();
      setStatus(statusData.data);

      // Get stats
      const statsResp = await fetch(
        `http://localhost:8080/api/v1/proxies/${proxyId}/stats?hours=1`
      );
      const statsData = await statsResp.json();
      setStats(statsData.data);
    }, 5000); // Update every 5 seconds

    return () => clearInterval(interval);
  }, [proxyId]);

  return (
    <div>
      <h2>Proxy: {status?.name}</h2>
      <div>Status: {status?.running ? '🟢 Running' : '🔴 Stopped'}</div>
      <div>Uptime: {status?.uptime}</div>
      <div>Requests: {stats?.total_requests}</div>
      <div>Avg Response: {stats?.avg_response_time_ms}ms</div>
    </div>
  );
}

Proxy API Troubleshooting

Proxy API Common Issues

1. Connection Refused

Ensure the unified API server is running: ./build/unified-admin
Check the server is listening on port 8080
Verify firewall settings

2. Proxy Won't Start

Check if the target server is accessible
Verify the port isn't already in use
Check proxy configuration is valid
Review logs: GET /api/v1/proxies/{id}/logs

3. Empty Statistics

Ensure the proxy is running
Verify traffic is being processed
Check if logs are being recorded properly

4. Policy Not Applied

Verify policy exists: GET /api/v1/proxies/{id}/policies
Check policy is active
Ensure policy is compatible with proxy type (MCP vs LLM)
Restart proxy after policy changes

5. Tool Discovery Fails (MCP)

Ensure MCP server is running and accessible
Verify MCP server implements tools/list method
Check network connectivity to target
Review error response for details

Proxy Debug Commands

bash

# Check API server health
curl -s http://localhost:8080/api/v1/health | jq

# Get all proxy statuses
curl -s http://localhost:8080/api/v1/proxies/status | jq

# Check specific proxy logs
curl -s "http://localhost:8080/api/v1/proxies/1/logs?limit=50" | jq

# Review system alerts
curl -s "http://localhost:8080/api/v1/system/alerts?time_range=1h" | jq

# Get system information
curl -s http://localhost:8080/api/v1/system/info | jq

Unified Web API Documentation: Complete API reference including system settings, alerts, and policies
API Examples: Comprehensive usage examples for all endpoints
Architecture Documentation: System architecture and design patterns

Proxy API Support

For issues, questions, or contributions:

GitHub Issues: ai-security-gateway/issues
Documentation: See the main documentation index
Examples: See API Examples for comprehensive usage examples

Proxy Management API Documentation ​

Proxy API Overview ​

Proxy API Base URL ​

Proxy API Authentication ​

Authentication Methods ​

1. JWT Token (Admin Users) ​

2. OAuth Session Token ​

3. API Key (Programmatic Access) ​

Role-Based Access Control ​

Quick Start Example ​

Endpoint Categories ​

Endpoint Overview ​

Configuration Endpoints ​

Lifecycle Endpoints ​

Monitoring Endpoints ​

Policy Endpoints ​

MCP Tool Management (MCP Proxies Only) ​

Proxy Core Endpoints ​

System Health Check ​

Proxy Configuration Management ​

List All Proxy Configurations ​

Create Proxy Configuration ​

Get Specific Proxy Configuration ​

Update Proxy Configuration ​

Delete Proxy Configuration ​

Proxy Lifecycle Control API ​

Start Proxy Instance ​

Stop Proxy Instance ​

Restart Proxy Instance ​

Get Proxy Status ​

Get All Proxy Statuses ​

Monitoring & Analytics ​

Get Proxy Logs ​

Get Proxy Statistics ​

Get Token Usage (LLM Proxies Only) ​

Policy Management API ​

Get Proxy Policies ​

Assign Multiple Policies ​

Add Single Policy ​

Remove Policy ​

MCP Tool Management API ​

List MCP Tools ​

Discover MCP Tools ​

Update Tool Status ​

Bulk Update Tools ​

Get Tool Statistics ​

Proxy API Error Handling ​

Proxy API Rate Limiting ​

WebSocket Endpoint ​

Proxy API Security Considerations ​

Proxy Integration Examples ​

Complete Proxy Setup ​

Monitor Proxy Health ​

Proxy SIEM Integration ​

Real-Time Dashboard ​

Proxy API Troubleshooting ​

Proxy API Common Issues ​

Proxy Debug Commands ​

Proxy API Related Documentation ​

Proxy API Support ​

Proxy Management API Documentation

Proxy API Overview

Proxy API Base URL

Proxy API Authentication

Authentication Methods

1. JWT Token (Admin Users)

2. OAuth Session Token

3. API Key (Programmatic Access)

Role-Based Access Control

Quick Start Example

Endpoint Categories

Endpoint Overview

Configuration Endpoints

Lifecycle Endpoints

Monitoring Endpoints

Policy Endpoints

MCP Tool Management (MCP Proxies Only)

Proxy Core Endpoints

System Health Check

Proxy Configuration Management

List All Proxy Configurations

Create Proxy Configuration

Get Specific Proxy Configuration

Update Proxy Configuration

Delete Proxy Configuration

Proxy Lifecycle Control API

Start Proxy Instance

Stop Proxy Instance

Restart Proxy Instance

Get Proxy Status

Get All Proxy Statuses

Monitoring & Analytics

Get Proxy Logs

Get Proxy Statistics

Get Token Usage (LLM Proxies Only)

Policy Management API

Get Proxy Policies

Assign Multiple Policies

Add Single Policy

Remove Policy

MCP Tool Management API

List MCP Tools

Discover MCP Tools

Update Tool Status

Bulk Update Tools

Get Tool Statistics

Proxy API Error Handling

Proxy API Rate Limiting

WebSocket Endpoint

Proxy API Security Considerations

Proxy Integration Examples

Complete Proxy Setup

Monitor Proxy Health

Proxy SIEM Integration

Real-Time Dashboard

Proxy API Troubleshooting

Proxy API Common Issues

Proxy Debug Commands

Proxy API Related Documentation

Proxy API Support