REST API

MCPProxy provides a REST API for server management and monitoring.

OpenAPI Specification

Interactive API documentation is available at http://127.0.0.1:8080/swagger/ when MCPProxy is running. The OpenAPI spec file is also available at oas/swagger.yaml.

Authentication

All /api/v1/* endpoints require authentication via API key:

# Using X-API-Key header (recommended)
curl -H "X-API-Key: your-api-key" http://127.0.0.1:8080/api/v1/servers

# Using query parameter
curl "http://127.0.0.1:8080/api/v1/servers?apikey=your-api-key"

Note: Unix socket connections bypass API key authentication (OS-level auth).

Base URL

http://127.0.0.1:8080/api/v1

Request ID Tracking

All API responses include an X-Request-Id header for request tracing and log correlation. This is useful for debugging issues and correlating errors with server logs.

Request Header

You can optionally provide your own request ID:

curl -H "X-API-Key: your-api-key" \
     -H "X-Request-Id: my-custom-id-123" \
     http://127.0.0.1:8080/api/v1/servers

Validation rules:

Pattern: ^[a-zA-Z0-9_-]{1,256}$
Max length: 256 characters
If missing or invalid, MCPProxy generates a UUID v4

Response Header

Every response includes the request ID:

X-Request-Id: my-custom-id-123

Error Responses

Error responses include the request_id in the JSON body for easy correlation:

{
  "success": false,
  "error": "server 'nonexistent' not found",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Log Correlation

Use the request ID to find related activity logs:

# Via CLI
mcpproxy activity list --request-id a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Via API
curl "http://127.0.0.1:8080/api/v1/activity?request_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Endpoints

Status

GET /api/v1/status

Get server status and statistics.

Response:

{
  "status": "running",
  "version": "0.11.0",
  "uptime": 3600,
  "servers": {
    "total": 5,
    "connected": 4,
    "quarantined": 1
  },
  "tools": {
    "total": 42
  }
}

Servers

GET /api/v1/servers

List all upstream servers with unified health status.

Response:

{
  "success": true,
  "data": {
    "servers": [
      {
        "name": "github-server",
        "protocol": "http",
        "enabled": true,
        "connected": true,
        "quarantined": false,
        "tool_count": 15,
        "health": {
          "level": "healthy",
          "admin_state": "enabled",
          "summary": "Connected (15 tools)",
          "action": ""
        }
      },
      {
        "name": "oauth-server",
        "protocol": "http",
        "enabled": true,
        "connected": false,
        "quarantined": false,
        "tool_count": 0,
        "health": {
          "level": "unhealthy",
          "admin_state": "enabled",
          "summary": "Token expired",
          "detail": "OAuth access token has expired",
          "action": "login"
        }
      }
    ]
  }
}

Health Object Fields:

Field	Type	Description
`level`	string	Health level: `healthy`, `degraded`, or `unhealthy`
`admin_state`	string	Admin state: `enabled`, `disabled`, or `quarantined`
`summary`	string	Human-readable status message
`detail`	string	Optional additional context about the status
`action`	string	Suggested remediation: `login`, `restart`, `enable`, `approve`, `view_logs`, or empty

POST /api/v1/servers/{name}/enable

Enable a server.

POST /api/v1/servers/{name}/disable

Disable a server.

POST /api/v1/servers/{name}/quarantine

Set quarantine status.

Request Body:

{
  "quarantined": true
}

POST /api/v1/servers/{name}/restart

Restart a server.

Tools

GET /api/v1/tools

Search tools across all servers.

Query Parameters:

q - Search query (optional)
limit - Maximum results (default: 15)

Response:

{
  "tools": [
    {
      "name": "github:create_issue",
      "server": "github-server",
      "description": "Create a new GitHub issue"
    }
  ]
}

GET /api/v1/servers/{name}/tools

List tools for a specific server.

Real-time Updates

GET /events

Server-Sent Events (SSE) stream for live updates.

curl "http://127.0.0.1:8080/events?apikey=your-api-key"

Events include:

servers.changed - Server status changed
config.reloaded - Configuration reloaded
tools.indexed - Tool index updated
activity.tool_call.started - Tool call initiated
activity.tool_call.completed - Tool call finished
activity.policy_decision - Tool call blocked by policy

Error Responses

{
  "error": "error message",
  "code": "ERROR_CODE"
}

Code	Description
401	Unauthorized - Invalid or missing API key
404	Not Found - Server or resource not found
500	Internal Server Error

Configuration

GET /api/v1/config

Get current configuration.

POST /api/v1/config/apply

Apply configuration changes.

POST /api/v1/config/validate

Validate configuration without applying.

Diagnostics

GET /api/v1/diagnostics

Get system diagnostics.

GET /api/v1/doctor

Run health checks (same as mcpproxy doctor CLI).

GET /api/v1/info

Get application info, version, and update availability.

Response:

{
  "success": true,
  "data": {
    "version": "v1.2.3",
    "web_ui_url": "http://127.0.0.1:8080/?apikey=xxx",
    "listen_addr": "127.0.0.1:8080",
    "endpoints": {
      "http": "127.0.0.1:8080",
      "socket": "/Users/user/.mcpproxy/mcpproxy.sock"
    },
    "update": {
      "available": true,
      "latest_version": "v1.3.0",
      "release_url": "https://github.com/smart-mcp-proxy/mcpproxy-go/releases/tag/v1.3.0",
      "checked_at": "2025-01-15T10:30:00Z",
      "is_prerelease": false
    }
  }
}

Response Fields:

Field	Type	Description
`version`	string	Current MCPProxy version
`web_ui_url`	string	URL to access the web control panel
`listen_addr`	string	Server listen address
`endpoints.http`	string	HTTP API endpoint address
`endpoints.socket`	string	Unix socket path (empty if disabled)
`update`	object	Update information (may be null if not checked yet)
`update.available`	boolean	Whether a newer version is available
`update.latest_version`	string	Latest version available on GitHub
`update.release_url`	string	URL to the GitHub release page
`update.checked_at`	string	ISO 8601 timestamp of last update check
`update.is_prerelease`	boolean	Whether the latest version is a prerelease
`update.check_error`	string	Error message if update check failed

Update Checking

MCPProxy automatically checks for updates every 4 hours. The update information is exposed via this endpoint and used by the tray application and web UI to show update notifications.

Docker

GET /api/v1/docker/status

Get Docker isolation status.

Secrets

GET /api/v1/secrets

List stored secrets.

GET /api/v1/secrets/{name}

Get secret metadata (not the value).

Sessions

GET /api/v1/sessions

List active MCP sessions.

GET /api/v1/sessions/{id}

Get session details.

Activity

Track and audit AI agent tool calls. See Activity Log for detailed documentation.

GET /api/v1/activity

List activity records with filtering and pagination.

Query Parameters:

Parameter	Type	Description
`type`	string	Filter by type: `tool_call`, `policy_decision`, `quarantine_change`, `server_change`
`server`	string	Filter by server name
`tool`	string	Filter by tool name
`session_id`	string	Filter by MCP session ID
`status`	string	Filter by status: `success`, `error`, `blocked`
`start_time`	string	Filter after this time (RFC3339)
`end_time`	string	Filter before this time (RFC3339)
`limit`	integer	Max records (1-100, default: 50)
`offset`	integer	Pagination offset (default: 0)

Response:

{
  "success": true,
  "data": {
    "activities": [
      {
        "id": "01JFXYZ123ABC",
        "type": "tool_call",
        "server_name": "github-server",
        "tool_name": "create_issue",
        "status": "success",
        "duration_ms": 245,
        "timestamp": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}

GET /api/v1/activity/{id}

Get full activity record details including request arguments and response data.

GET /api/v1/activity/export

Export activity records for compliance and auditing.

Query Parameters:

Parameter	Type	Description
`format`	string	Export format: `json` (JSON Lines) or `csv`
(filters)		Same filters as list endpoint

Example:

# Export as JSON Lines
curl -H "X-API-Key: $KEY" "http://127.0.0.1:8080/api/v1/activity/export?format=json"

# Export as CSV
curl -H "X-API-Key: $KEY" "http://127.0.0.1:8080/api/v1/activity/export?format=csv"

Bulk Operations

POST /api/v1/servers/enable_all

Enable all servers.

POST /api/v1/servers/disable_all

Disable all servers.

POST /api/v1/servers/restart_all

Restart all servers.

POST /api/v1/servers/reconnect

Reconnect all servers.

OpenAPI Specification

The complete OpenAPI 3.1 specification is available at:

/swagger/ - Interactive Swagger UI
/swagger/swagger.yaml - Raw specification

See oas/swagger.yaml in the repository for the complete API reference.

Authentication​

Base URL​

Request ID Tracking​

Request Header​

Response Header​

Error Responses​

Log Correlation​

Endpoints​

Status​

GET /api/v1/status​

Servers​

GET /api/v1/servers​

POST /api/v1/servers/{name}/enable​

POST /api/v1/servers/{name}/disable​

POST /api/v1/servers/{name}/quarantine​

POST /api/v1/servers/{name}/restart​

Tools​

GET /api/v1/tools​

GET /api/v1/servers/{name}/tools​

Real-time Updates​

GET /events​

Error Responses​

Configuration​

GET /api/v1/config​

POST /api/v1/config/apply​

POST /api/v1/config/validate​

Diagnostics​

GET /api/v1/diagnostics​

GET /api/v1/doctor​

GET /api/v1/info​

Docker​

GET /api/v1/docker/status​

Secrets​

GET /api/v1/secrets​

GET /api/v1/secrets/{name}​

Sessions​

GET /api/v1/sessions​

GET /api/v1/sessions/{id}​

Activity​

GET /api/v1/activity​

GET /api/v1/activity/{id}​

GET /api/v1/activity/export​

Bulk Operations​

POST /api/v1/servers/enable_all​

POST /api/v1/servers/disable_all​

POST /api/v1/servers/restart_all​

POST /api/v1/servers/reconnect​

OpenAPI Specification​

Authentication

Base URL

Request ID Tracking

Request Header

Response Header

Error Responses

Log Correlation

Endpoints

Status

GET /api/v1/status

Servers

GET /api/v1/servers

POST /api/v1/servers/{name}/enable

POST /api/v1/servers/{name}/disable

POST /api/v1/servers/{name}/quarantine

POST /api/v1/servers/{name}/restart

Tools

GET /api/v1/tools

GET /api/v1/servers/{name}/tools

Real-time Updates

GET /events

Error Responses

Configuration

GET /api/v1/config

POST /api/v1/config/apply

POST /api/v1/config/validate

Diagnostics

GET /api/v1/diagnostics

GET /api/v1/doctor

GET /api/v1/info

Docker

GET /api/v1/docker/status

Secrets

GET /api/v1/secrets

GET /api/v1/secrets/{name}

Sessions

GET /api/v1/sessions

GET /api/v1/sessions/{id}

Activity

GET /api/v1/activity

GET /api/v1/activity/{id}

GET /api/v1/activity/export

Bulk Operations

POST /api/v1/servers/enable_all

POST /api/v1/servers/disable_all

POST /api/v1/servers/restart_all

POST /api/v1/servers/reconnect

OpenAPI Specification