REST API Reference

MCPlexer exposes a REST API for managing configuration and querying runtime state. All endpoints are under the /api/v1 prefix.

Base URL: http://localhost:8080/api/v1

No authentication

The API has no authentication — it's designed for local use. All requests are trusted. Do not expose the API to untrusted networks without an auth proxy.

Health

GET/api/v1/health

Returns server health status.

Dashboard

GET/api/v1/dashboard?range=1h|6h|24h|7d

Returns a full dashboard snapshot including active sessions, downstream status, request stats, time series, tool leaderboard, server health, error breakdown, route hit map, approval metrics, and cache stats.

Dry Run

POST/api/v1/dry-run

Simulate route resolution for a tool call without executing it. Returns the matched route, downstream server, auth scope, and policy decision.

Body: {"workspace_id": "...", "tool_name": "github__list_repos"}

Workspaces

GET/api/v1/workspaces

List all workspaces.

POST/api/v1/workspaces

Create a new workspace.

Body: {"name": "...", "root_path": "/path/to/project", "default_policy": "allow|deny", "tags": {}}

GET/api/v1/workspaces/{id}

Get a workspace by ID.

PUT/api/v1/workspaces/{id}

Update a workspace.

DELETE/api/v1/workspaces/{id}

Delete a workspace.

Downstream Servers

GET/api/v1/downstreams

List all downstream server definitions.

POST/api/v1/downstreams

Create a new downstream server definition.

Body: {"name": "...", "command": "...", "args": [...], "env": {...}, "namespace": "..."}

GET/api/v1/downstreams/{id}

Get a downstream server by ID.

PUT/api/v1/downstreams/{id}

Update a downstream server definition.

DELETE/api/v1/downstreams/{id}

Delete a downstream server definition.

POST/api/v1/downstreams/{id}/discover

Trigger tool discovery on a downstream server. Starts the server process, queries its tool list, and stores the results.

POST/api/v1/downstreams/{id}/oauth-setup

Start the OAuth setup flow for a downstream server that requires OAuth authentication.

GET/api/v1/downstreams/{id}/oauth-status

Get the current OAuth status for a downstream server.

POST/api/v1/downstreams/{id}/connect

Connect to a downstream server using an existing OAuth token.

GET/api/v1/downstreams/{id}/oauth-capabilities

Get the OAuth capabilities and requirements for a downstream server.

Route Rules

GET/api/v1/routes

List all route rules.

POST/api/v1/routes

Create a new route rule.

Body: {"workspace_id": "...", "server_id": "...", "tool_pattern": "github__*", "policy": "allow", "priority": 100}

POST/api/v1/routes/bulk

Bulk create multiple route rules in a single request.

Body: {"rules": [{"workspace_id": "...", "server_id": "...", "tool_pattern": "...", "policy": "allow"}]}

GET/api/v1/routes/{id}

Get a route rule by ID.

PUT/api/v1/routes/{id}

Update a route rule.

DELETE/api/v1/routes/{id}

Delete a route rule.

Auth Scopes

GET/api/v1/auth-scopes

List all auth scopes.

POST/api/v1/auth-scopes

Create a new auth scope.

Body: {"name": "...", "server_id": "...", "env_vars": {...}}

GET/api/v1/auth-scopes/{id}

Get an auth scope by ID.

PUT/api/v1/auth-scopes/{id}

Update an auth scope.

DELETE/api/v1/auth-scopes/{id}

Delete an auth scope.

OAuth Operations

GET/api/v1/auth-scopes/{id}/oauth/authorize

Start the OAuth authorization flow. Returns a redirect URL to the OAuth provider.

GET/api/v1/auth-scopes/{id}/oauth/status

Get the current OAuth token status for an auth scope (valid, expired, or not configured).

POST/api/v1/auth-scopes/{id}/oauth/revoke

Revoke the OAuth token for an auth scope.

POST/api/v1/auth-scopes/oauth-quick-setup

Quick OAuth setup — creates an OAuth provider, auth scope, and starts the authorization flow in one step.

Body: {"provider_template": "github", "client_id": "...", "client_secret": "...", "server_id": "..."}

OAuth Providers

GET/api/v1/oauth-providers

List all OAuth provider configurations.

POST/api/v1/oauth-providers

Create a new OAuth provider.

Body: {"name": "...", "auth_url": "...", "token_url": "...", "client_id": "...", "client_secret": "...", "scopes": [...]}

GET/api/v1/oauth-providers/{id}

Get an OAuth provider by ID.

PUT/api/v1/oauth-providers/{id}

Update an OAuth provider.

DELETE/api/v1/oauth-providers/{id}

Delete an OAuth provider.

GET/api/v1/oauth-templates

List built-in OAuth provider templates (GitHub, Google, etc.).

POST/api/v1/oauth-providers/discover

Run OIDC discovery on a provider URL. Returns the discovered authorization, token, and userinfo endpoints.

OAuth Callback

GET/api/v1/oauth/callback

OAuth callback handler. Receives the authorization code from the OAuth provider and exchanges it for tokens.

Audit

GET/api/v1/audit

Query audit records with filtering and pagination.

Query params: session_id, workspace_id, tool_name, status, after, before, limit, offset

GET/api/v1/audit/stream

Server-Sent Events (SSE) stream of audit events. New tool call results are pushed in real time.

Approvals

GET/api/v1/approvals

List pending approval requests.

GET/api/v1/approvals/{id}

Get details of a specific approval request.

POST/api/v1/approvals/{id}/resolve

Resolve a pending approval request.

Body: {"approved": true, "resolution": "Looks good"}

GET/api/v1/approvals/stream

Server-Sent Events (SSE) stream of approval events. New requests and resolutions are pushed in real time.

Cache

GET/api/v1/cache/stats

Get cache statistics for both tool call and route resolution caches. Returns hits, misses, and hit rates.

POST/api/v1/cache/flush

Flush cached entries.

Body: {"layer": "tool_call|route|all", "server_id": "optional-server-id"}

Settings

GET/api/v1/settings

Get current settings. Returns the active settings (merged from defaults, database, and environment variable overrides) plus the default descriptions for all built-in tools.

PUT/api/v1/settings

Update settings. Validates and persists to the database. Environment variable overrides still take precedence on read.

Body: {"slim_tools": true, "tools_cache_ttl_sec": 15, "log_level": "info", "codex_dynamic_tool_compat": true, "tool_description_overrides": {}}

MCP Install

Manage MCPlexer's installation in MCP client applications (Claude Desktop, Cursor, Codex, etc.).

GET/api/v1/mcp-install/status

List all known MCP clients with detection status (installed on this machine), configuration status (MCPlexer entry present), binary path, and the server entry JSON.

POST/api/v1/mcp-install/{clientId}/install

Write the MCPlexer server entry into a client's MCP config file. The client must be detected on this machine.

POST/api/v1/mcp-install/{clientId}/uninstall

Remove the MCPlexer server entry from a client's MCP config file.

GET/api/v1/mcp-install/{clientId}/preview

Preview what the client's config file would look like after installing MCPlexer, without writing any changes.

Dashboard & Web UI Control Server