Endpoints - Argus MCP

All endpoints are relative to /manage/v1/.

`GET /health`

Liveness and readiness probe. Always public -- no token required.

Response

{
  "status": "healthy",
  "uptime_seconds": 3600.5,
  "version": "0.8.0",
  "backends": {
    "total": 3,
    "connected": 3,
    "healthy": 2
  }
}

Field	Type	Description
`status`	string	`"healthy"`, `"degraded"`, or `"unhealthy"`
`uptime_seconds`	float	Seconds since server start
`version`	string	Server version
`backends.total`	int	Total configured backends
`backends.connected`	int	Currently connected backends
`backends.healthy`	int	Backends passing health checks

Status logic:

healthy -- all backends connected and healthy
degraded -- some backends unhealthy or disconnected
unhealthy -- no backends connected

`GET /ready`

Readiness probe. Returns 200 when the gateway is accepting traffic. Returns 503 when backends are not yet connected. Always public -- no token required.

Response

200 OK (gateway ready):

{
  "ready": true,
  "reason": "accepting traffic"
}

503 Service Unavailable (not ready):

{
  "ready": false,
  "reason": "backends not connected"
}

Field	Type	Description
`ready`	boolean	Whether the gateway is ready to serve traffic
`reason`	string	Human-readable readiness status message

`GET /status`

Full service status including config and transport info.

Response

{
  "service": {
    "name": "Argus MCP",
    "version": "0.8.0",
    "state": "running",
    "uptime_seconds": 3600.5,
    "started_at": "2026-02-23T12:00:00Z"
  },
  "config": {
    "file_path": "/path/to/config.yaml",
    "loaded_at": "2026-02-23T12:00:00Z",
    "backend_count": 3
  },
  "transport": {
    "sse_url": "http://127.0.0.1:9000/sse",
    "streamable_http_url": "http://127.0.0.1:9000/mcp",
    "host": "127.0.0.1",
    "port": 9000
  },
  "feature_flags": {
    "optimizer": false,
    "hot_reload": true,
    "outgoing_auth": true,
    "session_management": true,
    "yaml_config": true
  }
}

`GET /backends`

List all backend connections with state, health, and capabilities.

Response

{
  "backends": [
    {
      "name": "my-server",
      "type": "stdio",
      "group": "default",
      "phase": "Ready",
      "state": "connected",
      "error": null,
      "capabilities": {
        "tools": 5,
        "resources": 2,
        "prompts": 1
      },
      "health": {
        "status": "healthy",
        "last_check": null,
        "latency_ms": null
      },
      "conditions": [
        {
          "type": "Ready",
          "status": true,
          "reason": "Connected",
          "message": "Backend initialized successfully",
          "last_transition": "2026-02-23T12:00:00Z"
        }
      ],
      "labels": {}
    }
  ]
}

Field	Type	Description
`name`	string	Backend identifier (from config key)
`type`	string	`"stdio"`, `"sse"`, or `"streamable-http"`
`group`	string	Logical server group
`phase`	string	Lifecycle phase (see below)
`state`	string	Connection state
`error`	string?	Error message if failed
`capabilities`	object	Capability counts
`health`	object	Health check (`status`, `last_check`, `latency_ms`)
`conditions`	array	Structured conditions

Lifecycle phases: Pending, Initializing, Ready, Degraded, Failed, ShuttingDown

`GET /groups`

List logical server groups and their members.

Query Parameters

Param	Type	Description
`group`	string	Filter by group name (optional)

Response

{
  "groups": {
    "default": {
      "servers": ["server-a", "server-b"],
      "count": 2
    },
    "search-tools": {
      "servers": ["search-server"],
      "count": 1
    }
  },
  "total_groups": 2,
  "total_servers": 3
}

`GET /capabilities`

Aggregated tools, resources, and prompts from all connected backends.

Query Parameters

Param	Type	Description
`type`	string	Filter by type: `tools`, `resources`, `prompts`
`backend`	string	Filter by backend name
`search`	string	Search capability names

Response

{
  "tools": [
    {
      "name": "search_web",
      "original_name": "search_web",
      "description": "Search the web",
      "backend": "browser-server",
      "input_schema": { },
      "filtered": false,
      "renamed": false
    }
  ],
  "resources": [
    {
      "uri": "docs://readme",
      "name": "docs://readme",
      "backend": "docs-server",
      "mime_type": "text/markdown"
    }
  ],
  "prompts": [
    {
      "name": "code_review",
      "description": "Review code changes",
      "backend": "review-server",
      "arguments": []
    }
  ],
  "route_map": {
    "search_web": ["browser-server", "search_web"],
    "docs://readme": ["docs-server", "docs://readme"]
  }
}

`GET /sessions`

List active MCP client sessions.

Response

{
  "active_sessions": 2,
  "sessions": [
    {
      "id": "abc123",
      "transport_type": "sse",
      "tool_count": 15,
      "capability_snapshot": { "tools": 15, "resources": 3, "prompts": 2 },
      "age_seconds": 120.5,
      "idle_seconds": 10.2,
      "ttl": 3600,
      "expired": false
    }
  ]
}

`GET /events`

Recent events (polling-based).

Query Parameters

Param	Type	Default	Description
`limit`	int	100	Maximum events to return
`since`	ISO string	--	Return events after this timestamp
`severity`	string	--	Filter by severity level

Response

{
  "events": [
    {
      "id": "evt_abc123",
      "timestamp": "2026-02-23T12:01:00Z",
      "stage": "connected",
      "message": "Backend 'my-server' connected successfully",
      "severity": "info",
      "backend": "my-server",
      "details": {}
    }
  ]
}

`GET /events/stream`

Real-time event stream via Server-Sent Events (SSE).

Usage

curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:9000/manage/v1/events/stream

Events are sent as SSE data: frames (JSON). A heartbeat comment is sent every 30 seconds to keep the connection alive.

data: {"id": "evt_abc", "timestamp": "...", "stage": "connected", ...}

data: {"id": "evt_def", "timestamp": "...", "stage": "error", ...}

: heartbeat

`GET /batch`

Combined status, backends, capabilities, and recent events in a single round-trip. Designed for polling clients (TUI) to eliminate per-poll multi-request overhead.

Query Parameters

Param	Type	Default	Description
`events_limit`	int	20	Maximum events to include in the response

Response

{
  "status": { ... },
  "backends": { ... },
  "capabilities": { ... },
  "events": { ... }
}

Field	Type	Description
`status`	object	Service status (same schema as `GET /status`)
`backends`	object	Backend list (same schema as `GET /backends`)
`capabilities`	object	Aggregated capabilities (same schema as `GET /capabilities`)
`events`	object	Recent events (same schema as `GET /events`)

Note:

The status, backends, capabilities, and events objects have the same schemas as the respective individual endpoints.

`POST /reload`

Hot-reload the configuration file. Detects changes and reconnects affected backends.

Note:

Requires feature_flags.hot_reload: true in config.

Response

{
  "reloaded": true,
  "backends_added": ["new-server"],
  "backends_removed": ["old-server"],
  "backends_changed": ["modified-server"],
  "errors": []
}

`POST /reconnect/{name}`

Reconnect a specific backend by name.

Path Parameters

Param	Type	Description
`name`	string	Backend name (from config)

Response

{
  "name": "my-server",
  "reconnected": true,
  "error": null
}

Returns 404 if the backend name is not found.

`POST /reauth/{name}`

Trigger interactive re-authentication for a backend using PKCE or OAuth2. Initiates the browser-based auth flow for the named backend.

Path Parameters

Param	Type	Description
`name`	string	Backend name from config

Response

{
  "name": "my-server",
  "reauth_initiated": true,
  "error": null
}

Field	Type	Description
`name`	string	Backend name
`reauth_initiated`	boolean	Whether the re-auth flow was started
`error`	string?	Error message if initiation failed

Returns 404 if the backend name is not found. Returns 503 if the service is not running.

`POST /shutdown`

Initiate graceful server shutdown.

Request Body (optional)

{
  "timeout_seconds": 30
}

Response

{
  "shutting_down": true
}

The server will:

Stop accepting new connections
Complete in-flight requests
Disconnect all backends
Exit the process

`GET /registry/search`

Search external MCP server registries (Glama, Smithery, etc.) for available servers.

Query Parameters

Param	Type	Default	Description
`q`	string	required	Search query -- alphanumeric and spaces only
`limit`	int	20	Maximum results to return (max 100)
`registry`	string	--	Filter to a specific registry by name (optional)

Response

{
  "servers": [
    {
      "name": "brave-search",
      "description": "Web search via Brave Search API",
      "transport": "stdio",
      "url": "",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "version": "1.0.0",
      "categories": ["search", "web"]
    }
  ],
  "registry": "glama",
  "total": 1
}

Field	Type	Description
`servers`	array	List of matching registry entries
`registry`	string	Name of the registry that returned results
`total`	int	Total number of results returned

RegistryServerEntry fields:

Field	Type	Description
`name`	string	Server identifier
`description`	string	Server description
`transport`	string	Transport type (`stdio`, `sse`, etc.)
`url`	string	Server URL (for HTTP transports)
`command`	string	Launch command (for stdio)
`args`	array	Command arguments
`version`	string	Server version
`categories`	array	Category tags

Returns 400 if q is missing or invalid. Returns 404 if no registries are configured or the specified registry is not found.

`GET /skills`

List all installed skills and their enabled/disabled status.

Response

{
  "skills": [
    {
      "name": "my-skill",
      "version": "1.0.0",
      "description": "A skill that provides extra tools",
      "status": "enabled",
      "tools": 3,
      "workflows": 1,
      "author": "Alice"
    }
  ]
}

Field	Type	Description
`name`	string	Skill identifier
`version`	string	Skill version
`description`	string	Skill description
`status`	string	`"enabled"` or `"disabled"`
`tools`	int	Number of tools provided by the skill
`workflows`	int	Number of workflows provided by the skill
`author`	string	Skill author

Returns 503 if the skill manager is not initialized.

`POST /skills/{name}/enable`

Enable an installed skill by name.

Path Parameters

Param	Type	Description
`name`	string	Skill name

Response

{
  "name": "my-skill",
  "action": "enabled",
  "ok": true
}

Field	Type	Description
`name`	string	Skill name
`action`	string	Action performed (`"enabled"`)
`ok`	boolean	Whether the action succeeded

Returns 404 if the skill is not found. Returns 503 if the skill manager is not initialized.

`POST /skills/{name}/disable`

Disable an installed skill by name.

Path Parameters

Param	Type	Description
`name`	string	Skill name

Response

{
  "name": "my-skill",
  "action": "disabled",
  "ok": true
}

Field	Type	Description
`name`	string	Skill name
`action`	string	Action performed (`"disabled"`)
`ok`	boolean	Whether the action succeeded

Returns 404 if the skill is not found. Returns 503 if the skill manager is not initialized.

`POST /tools/call`

Proxy an MCP tools/call request to the correct backend. Routes the call using the internal capability registry and returns the backend's response.

Request Body

{
  "tool": "search_web",
  "arguments": { "query": "MCP servers" }
}

Field	Type	Description
`tool`	string	Required. Tool name as exposed by the gateway
`arguments`	object	Required. Tool arguments -- use `{}` for no args

Response

{
  "tool": "search_web",
  "backend": "browser-server",
  "content": [
    { "type": "text", "text": "Search results..." }
  ],
  "isError": false
}

Field	Type	Description
`tool`	string	Tool name that was called
`backend`	string	Backend that handled the call
`content`	array	Result content items (`type`, `text`)
`isError`	boolean	Whether the tool returned an error result

Returns 404 if the tool is not found. Returns 503 if the backend session is unavailable. Returns 502 if the call fails.

`POST /resources/read`

Proxy an MCP resources/read request to the correct backend. Routes by URI using the internal capability registry.

Request Body

{
  "uri": "docs://readme"
}

Field	Type	Description
`uri`	string	Required. Resource URI as exposed by the gateway

Response

{
  "uri": "docs://readme",
  "backend": "docs-server",
  "contents": [
    {
      "uri": "docs://readme",
      "text": "# Readme\n...",
      "mimeType": "text/markdown"
    }
  ]
}

Field	Type	Description
`uri`	string	Resource URI that was read
`backend`	string	Backend that handled the read
`contents`	array	Resource content items (`uri`, `text`, `mimeType`)

Returns 404 if the resource is not found. Returns 503 if the backend is unavailable. Returns 502 if the read fails.

API Reference YAML Cookbook