Sauron

  # Sauron Integration

Botpress Cloud internal admin & operations tool. Look up any workspace, bot, user, integration, or entity by ID or name. Debug issues with logs, traces, and error analysis. Browse the full software & infrastructure catalog (services, repos, libraries, databases, clusters). Search code across all Botpress repositories. Analyze billing, usage, quotas, and LLM costs. Monitor ECS services, databases, Lambdas, and infrastructure health.

## Available Tools

- **find_by_id**: Find any entity by ID. Returns comprehensive entity details including relationships (parent/child), metadata, and current status. Supports bots, workspaces, conversations, integrations, users, and much more.
- **find_by_name**: Search entities by name using fuzzy matching. Returns list of matching bots, workspaces, integrations, and accounts with basic information. Minimum 3 characters required.
- **list_actions**: Returns list of all scheduled and completed actions with execution status, timestamps, and error logs. Supports cursor pagination.
- **find_accounts**: Searches user accounts by email, name, or ID. Returns list of accounts with workspace memberships, roles, creation dates, and last activity timestamps.
  Pagination: - Use cursor-based pagination by passing the nextCursor from previous response - Or use offset-based pagination with limit + offset parameters
- **get_bot_overview**: Returns bot overview with basic info and integrations. Fast query (<100ms).
- **get_bot_activity_summary**: Returns detailed bot activity metrics and trends. ⚠️ SLOW: 30-45s in production. Use getBotOverview first for quick info.
- **get_bot_configuration**: Returns the full bot configuration for debugging: autonomous nodes with guidelines, code snippets, workflows, knowledge bases, settings, and hooks. Use this to understand how a bot is configured and debug logic issues.
- **find_bots**: Searches bots by name, workspace, status with pagination and filtering. Returns list of bots with basic information.
  Pagination: - Use cursor-based pagination by passing the nextCursor from previous response - Or use offset-based pagination with limit + offset parameters
- **get_bot_stats**: Returns bot statistics over specified time period: messages, users, errors, response times, and trend analysis.
- **get_bot_timeline**: Returns bot deployment and configuration change history with timestamps, versions, and change descriptions.
- **get_bot_json**: Returns bot definition with progressive disclosure. CACHED for 2 minutes.

Modes:

1. Summary (default): { botId } - Overview with IDs, counts
2. Section focus: { botId, sections: ["flows"] } - FULL RAW JSON for section
3. Entity drilling: { botId, flowIds: ["flow-1"] } - FULL RAW JSON for specific entities

Available sections: flows, tables, knowledge_base, actions, hooks, intents, capabilities, agents, settings, schemas, entities

When you specify sections or IDs, you get COMPLETE raw JSON - NOTHING is truncated.
Use sanitizeSensitive: false to see actual API keys/secrets.

- **get_bot_versions**: Lists all bot versions from S3 with timestamps and metadata. Use this to find versions deployed between specific dates for comparison.
- **get_bot_version**: Fetches complete bot JSON for a specific version. Returns summarized overview showing key configuration changes. Use after getBotVersions to compare specific versions.
- **compare_bot_versions**: Compares two bot versions and identifies all changes (workflows, integrations, states, events, configuration). Returns structured diff showing what was added, removed, or modified. Use this to diagnose issues when bot behavior changed between deployments.
- **get_bot_issues**: Returns errors and issues grouped by type and frequency with stack traces, occurrence counts, and timestamps.
- **get_llm_analytics**: Returns LLM usage analytics: token counts, costs by model, latency metrics, and error rates.
- **get_workspace_overview**: Returns workspace overview with bots, members, and plan details. Fast query (<100ms).
- **get_workspace_bot_activities**: Returns bot activity metrics for workspace: message counts, conversation counts, and activity trends per bot. Use when you need to analyze bot usage patterns.
- **get_workspace_usage_and_audits**: Returns workspace usage metrics by period with quota tracking and recent audit log entries. Use when you need usage analytics or activity history.
- **find_workspaces**: Searches workspaces by name, ID, or filters with pagination. Returns list with basic info, bot counts, member counts, and plan information. Supports cursor pagination.
- **get_workspace_usage**: Returns workspace usage metrics: message counts by period, AI token usage, storage consumption, API call volumes.
- **get_workspace_plan_summary**: Returns Stripe plan and subscription details: plan name, billing cycle, price, features, and renewal date.
- **get_workspace_billing**: Returns workspace billing information: current plan, payment method details, subscription status, and billing history.
- **get_workspace_auto_recharge**: Returns workspace auto-recharge configuration: enabled status, threshold amount, recharge amount, payment method.
- **get_auto_recharge_transactions**: Returns auto-recharge transaction history with amounts, timestamps, status, and payment method details.
- **get_workspace_audits**: Returns workspace audit log entries: user actions, configuration changes, system events with timestamps and user attribution.
- **list_llm_models**: Returns list of available cognitive/LLM models with IDs, names, providers, and capabilities.
- **get_model_requests**: Returns recent requests made to specific cognitive model with timestamps, durations, token counts, and status codes.
- **get_conversation_messages**: Returns paginated conversation messages with text, sender, timestamps, and metadata. Shows sample messages for MCP - use limit/offset for pagination.
- **get_conversation_events**: Returns conversation events: user joined, bot action, state changes, errors with timestamps and details. Shows grouped summary for MCP.
- **summarize_conversation**: Returns AI-generated summary of conversation including key topics, outcomes, and user sentiment.
- **get_bot_conversations**: Returns list of conversations for bot with filters, pagination, user info, and last message timestamps. Supports cursor pagination.
- **get_github_deployment_workflows**: Returns all GitHub Actions workflows across Botpress repositories with status, run history, and success rates (including if they are disabled)
- **get_repository_index**: Get searchable index of all Botpress repositories with metadata, categories, and key paths. Use to discover which repositories to search for code references.
- **search_code**: Search code across Botpress repositories using GitHub Code Search API. Token-efficient implementation with optimized results view.
- **search_links**: Search resource links (documentation, monitoring dashboards, GitHub repos, runbooks, and other important resources) by name, description, or tags. Use search parameter to filter results.
- **search_catalog**: Search the Botpress Software & Infrastructure Catalog. Returns detailed info on any service, repository, library, database, cluster, or package in the platform — including descriptions, repo links, and IDs. Use this FIRST when you need to understand what a service is, find a repo URL, or discover platform components. Supports keyword search and filtering by type (service, library, database, cluster, repository, package, external-service) or category (core, data, infrastructure, frontend, observability, libraries).
- **get_global_insights**: Returns platform-wide insights: total messages, active bots, user engagement, error rates, and health metrics.
- **find_insights_by_ip**: Returns insights for specific IP address: associated users, bots accessed, activity patterns, and anomaly detection.
- **find_bot_insights**: Returns bot-specific insights with time-series data: messages, users, sessions, engagement metrics, and trends.
- **find_customer_health**: Returns customer health score and engagement metrics: activity level, error rate, support tickets, churn risk.
- **get_integrations**: Returns list of integrations with version counts, status, verification status, and lifecycle information. Supports cursor pagination.
- **get_integration_versions**: Returns all versions for specific integration with deployment dates, status, consumer count, and changelog.
- **get_interfaces**: Returns list of interfaces (webchat, etc) with version counts, status, and configuration information. Supports cursor pagination.
- **get_interface_versions**: Returns all versions for specific interface with deployment dates, status, consumer count, and feature list.
- **find_issues**: Searches issues by bot, workspace, type, or time range. Returns paginated list with error details and occurrence counts.
- **get_top_issues**: Returns top platform issues and errors across all bots and workspaces, ranked by frequency and severity. Shows condensed summary for MCP without verbose stack traces.
- **get_issue_events**: Returns individual error events for specific issue with timestamps, context, user impact, and stack traces.
- **get_lambda_logs**: Returns CloudWatch logs for Lambda function with filtering by time range and log level. Includes error pattern detection.
- **get_lambda_metrics**: Returns Lambda metrics: invocation count, errors, duration, throttles, concurrent executions. Includes trends and performance analysis.
- **find_service_logs**: Query platform services logs. Modes: `patterns` (default) groups errors by pattern, `search` finds matches with timeline, `detailed` returns full log lines. Workflow: patterns -> search -> detailed.
- **find_web_requests**: Query HTTP traffic logs. Modes: `patterns` (default) groups errors by pattern, `search` finds matches with timeline, `detailed` returns full log lines. Workflow: patterns -> search -> detailed.
- **get_bot_cloud_logs**: Query bot execution logs. Modes: `patterns` (default) groups errors by pattern, `search` finds matches with timeline, `detailed` returns full log lines (supports contextLines for surrounding logs). Workflow: patterns -> search -> detailed.
- **get_integration_cloud_logs**: Query integration execution logs. Modes: `patterns` (default) groups errors by pattern, `search` finds matches with timeline, `detailed` returns full log lines (supports contextLines for surrounding logs). Workflow: patterns -> search -> detailed.
- **find_top_log_patterns**: Returns most frequent log patterns ranked by occurrence count with sample messages and timestamps. Analyzes logs across multiple bots.
- **get_top_bots_activity**: ⚠️ EXPENSIVE: Returns most active bots ranked by message volume with statistics and activity trends. This is a very expensive query and should be used with caution.
- **list_ecs_clusters**: Returns all ECS clusters (grouped services). Each cluster may contain multiple services deployed together.
- **list_ecs_services**: Returns all individual ECS services (not grouped by cluster). Shows each service with its configuration.
- **get_ecs_service_details**: Returns detailed ECS service information: running tasks, deployments, events, configuration, and load balancer status.
- **get_blocked_ips**: Returns list of blocked IP addresses with block reasons, timestamps, and violation counts.
- **get_plugins**: Returns list of plugins with version counts, status, and lifecycle information. Supports cursor pagination.
- **get_plugin_versions**: Returns all versions for specific plugin with deployment dates, status, consumer count, and changelog.
- **list_databases**: Returns list of all connected PostgreSQL databases with connection status, version, and size.
- **get_database_overview**: Returns PostgreSQL database overview: size, connection count, table count, index count, and performance metrics.
- **get_query_stats**: Returns PostgreSQL query performance statistics from pg_stat_statements: execution count, total time, mean time, slowest queries. May take 30+ seconds on large databases with high query volume.
- **get_active_queries**: Returns currently executing PostgreSQL queries with SQL text, duration, state, waiting status, and client info.
- **get_rds_performance_insights**: Returns AWS RDS Performance Insights metrics: CPU, memory, IOPS, connections, wait events.
- **get_database_config**: Returns PostgreSQL configuration parameters and current values: memory settings, connection limits, autovacuum settings.
- **get_llm_analytics_overview**: Returns LLM analytics overview: token usage, costs, request counts, by time period and optional bot filter.
- **who_am_i**: Returns current authenticated user information: email, admin status, active status, and permissions list.
- **get_mcp_tools**: Returns list of all MCP tools available in Sauron with their descriptions and input schemas.
- **get_bot_tables**: Returns all custom tables for bot with row counts, schemas, and last modified timestamps.
- **find_trace_details**: Search for all logs related to a specific trace ID, across all services. We recommend specifying a timeframe of +- 5 minutes for a quicker response.
- **get_usage_vs_quotas**: Returns actual USAGE vs QUOTA comparison for a workspace or bot: message counts, AI spend, storage, etc. Shows consumption over time with over-quota alerts. Different from get_workspace_usage which returns raw metrics — this tool shows how close usage is to the limits. Use `list_quotas` to see just the limits.
- **list_base_quotas**: Returns BASE quotas (custom additional limits) added via Sauron for a workspace. These are additions beyond plan defaults. Use `listQuotas` to see total effective limits (plan defaults + these additions).
- **list_quotas**: Returns EFFECTIVE quotas (total enforced limits) for a workspace: plan defaults + custom additions. These are the actual limits enforced. Use `listBaseQuotas` to see only administrator additions, or `getUsage` to compare against actual consumption.

## Configuration

- **MCP Server URL**: The URL of the MCP server
- **Auth Token** (optional): Authentication token if required by the server

## Usage

This integration provides access to all tools exposed by the Sauron MCP server. Each tool is available as a separate action in Botpress.