Skip to main content

Admin Tools Overview

Overview​

The Mastra admin surface exposes a small, restricted set of operational tools for managing agent profiles, testing integrations, and performing health checks. These tools are implemented in packages/platform-runtime/src/tools/admin and are registered via packages/platform-runtime/src/tools/admin/index.ts.

warning

Access Control: These tools are exposed on the Admin MCP Server and HTTP admin endpoints. Browser/Admin UI callers should use the dashboard BFF path, where APIM authenticates the request and the dashboard injects the runtime admin proxy secret upstream. Direct runtime /admin/tools/* calls are operator/service-to-service paths and require the runtime admin proxy secret when that guard is enabled.

Available Tools​

Agent Profile Management​

  • Update Agent Profile - Create or update agent prompts and LLM parameters
  • List Agent Profiles - View all current agent profiles
  • Agent Profile History - Audit version history for agent profiles
  • Get Current Profile (admin-get-current-profile) - Read the current active profile for an agent (used by Prompt Tuner)

System Health & Testing​

  • Database Health Check - Verify database connectivity and schema health
  • Environment Health (admin-environment-health) - Probe configured service health for an environment
  • Observability Analytics (admin-observability-analytics) - Query supported operational analytics summaries
  • Test LLM Model - Test LLM configurations and parameters
  • Probe LLM Provider - Full diagnostic probe for any provider: reasoning models, streaming, function calling, parameter strip diagnostics
  • Test Tavily Search - Test and inspect web search integration

Authentication​

Browser/Replit Admin UI code should use the Admin UI BFF (/admin-api/* locally, /dashboard/admin-api/* in testing) instead of calling runtime tool routes directly. The direct runtime route is POST /admin/tools/{slug}. The generated compatibility route POST /api/tools/{tool-id}/execute also exists and may be APIM-published as /ai/api/tools/{tool-id}/execute.

curl -X POST "${DASHBOARD_BASE_URL}/dashboard/admin-api/admin/tools/{slug}" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: ${APIM_SUBSCRIPTION_KEY}" \
  -d '{...}'

Implementation Details​

  • Tool implementations: packages/platform-runtime/src/tools/admin/
  • Registration: packages/platform-runtime/src/tools/admin/index.ts
  • Admin MCP server: src/mastra/mcp-servers/admin-server.ts
  • Tests: tests/admin/unit/tools/**

Environment Configuration​

Most admin tools require specific environment variables. See individual tool pages for detailed configuration requirements.

Common variables:

  • MASTRA_BASE_URL - Base URL for the Mastra API
  • AZURE_SQL_* - Database connection settings (for profile and health check tools)
  • TAVILY_API_KEY - Required for Tavily search testing