MCP Tool: logs

Read recent server logs for debugging and development. The logs tool exposes the server's in-memory log ring buffer to authorized callers.

Overview

logs returns recent entries from the server's ring buffer, letting an agent debug Sibyl behavior without direct access to the host. It is a developer-introspection tool.

This tool requires the OWNER role (the super-admin equivalent). Callers without OWNER membership receive an authorization error.

Input Schema

interface LogsInput {
  limit?: number; // Max entries to return, clamped 1-500 (default 50)
  service?: string; // Filter by service name ("api", "worker")
  level?: string; // Filter by log level ("debug", "info", "warning", "error")
}

The limit argument is clamped to the range 1-500 regardless of the value supplied. The ring buffer retains the most recent entries only; older entries are dropped as new ones arrive.

Response Schema

The tool returns a list of log entries, newest last.

type LogsResponse = LogEntry[];

interface LogEntry {
  timestamp: string; // ISO 8601 timestamp
  service: string; // "api" or "worker"
  level: string; // "debug", "info", "warning", "error"
  event: string; // Log event name
  context: Record<string, any>; // Structured log context fields
}

Usage Examples

Recent Entries

{
  "name": "logs",
  "arguments": {}
}

Returns the last 50 entries.

More Entries

{
  "name": "logs",
  "arguments": { "limit": 200 }
}

Worker Logs Only

{
  "name": "logs",
  "arguments": { "service": "worker" }
}

Errors Only

{
  "name": "logs",
  "arguments": { "level": "error", "limit": 100 }
}

Worker Errors

{
  "name": "logs",
  "arguments": { "service": "worker", "level": "error" }
}

Notes

• The buffer is in-memory and per-process. In a multi-process deployment, logs returns entries from the process that handled the call.
• Use level: "error" first when diagnosing a failure, then widen to warning or info.
• The CLI sibyl logs tail command exposes the same buffer with streaming support (sibyl logs tail -f).
• The REST equivalent is GET /api/logs, with a WebSocket stream at /api/logs/stream.

Error Handling

Error	Cause	Resolution
Organization context required	No org-scoped token	Authenticate with an org-scoped token
OWNER role required for log access	Caller is not an org OWNER	Use an OWNER credential

Related

• mcp-manage.md - Admin actions (health, stats)
• auth-authorization.md - Roles and the OWNER role