Admin & Operations Tools

Admin tools — Overview

The Mastra admin surface exposes a small, restricted set of operational tools for managing agent profiles 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.

Access: the tools are exposed on the Admin MCP Server and the HTTP admin endpoints. These endpoints are protected by APIM and require either an APIM subscription key or a bearer token. For tenant-hosted automation and in-production environments, prefer OAuth bearer tokens (client credentials) over subscription keys—subscription keys are an APIM-level artifact and work as a fallback for simple curl examples.

Route Families

Admin tools have three source-backed HTTP shapes:

Route family	Example	Use
Domain admin tool route	POST /admin/tools/list-agent-profiles	Preferred for direct runtime/API documentation. Accepts flat JSON and the legacy { "data": { ... } } wrapper.
Generic Mastra tool route	POST /api/tools/admin-list-agent-profiles/execute	Generated compatibility route; APIM may publish it as /ai/api/tools/admin-list-agent-profiles/execute.
Admin UI BFF	Local /admin-api/admin/*, testing /dashboard/admin-api/*	Browser/Replit Admin UI path. Use this for UI development instead of calling runtime tool routes directly.

Tools

Tool	Purpose
admin-update-agent-profile	Upserts a new prompt/profile version for a given agent (hashes payload, expires previous current row, increments version, returns the new record). Use this to seed or update agent prompts programmatically.
admin-list-agent-profiles	Returns all current (IsCurrent = 1) agent profiles for dashboard dropdowns (includes agentId + agentAlias).
admin-agent-profile-history	Returns version history for an agentId so you can audit past prompts and LLM knob overrides.
admin-get-current-profile	Returns the current active profile for a specific agent.
admin-db-health-check	Runs quick DB inventory queries (row counts and samples) to verify connectivity and schema health.
admin-environment-health	Probes configured service health for an environment.
admin-observability-analytics	Returns supported operational analytics summaries.
admin-test-llm-model / admin-probe-llm-provider	Validate model/provider behavior and effective parameter support.
admin-test-tavily-search	Validates configured Tavily search behavior.
admin-update-llm-params	Writes versioned, capability-validated model parameter defaults.

HTTP examples (curl)

All admin tools are available on the same base server URL as other Mastra endpoints. Supply either a subscription key or a bearer token for authentication.

• List profiles

curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/list-agent-profiles" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -d '{}'

• Update an agent profile

curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/update-agent-profile" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -d '{"data": {"agentId": "k12-safety-agent", "systemPrompt": "You are the safety agent...", "llmOverrides": {"temperature": 0.3}, "createdBy": "ops@example.com"}}'

• Get profile history

curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/agent-profile-history" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: $SUBSCRIPTION_KEY" \
  -d '{"data": {"agentId": "k12-safety-agent"}}'

• DB health check

curl -s -X POST "${MASTRA_BASE_URL}/admin/tools/db-health-check" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -d '{}'

Node / JS example

The same endpoints are callable programmatically using node or any HTTP client:

import fetch from 'node-fetch';

const MASTRA_BASE_URL = process.env.MASTRA_BASE_URL;
const res = await fetch(`${MASTRA_BASE_URL}/admin/tools/update-agent-profile`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.BEARER_TOKEN}`,
  },
  body: JSON.stringify({ data: { agentId: 'k12-safety-agent', systemPrompt: '...', createdBy: 'ops@example.com' } })
});
const json = await res.json();
console.log(json);

Where to find the implementations and tests

• 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/**

Bruno examples can be added to this page. Keep examples routed through either the preferred /admin/tools/{slug} surface or the generated /api/tools/{tool-id}/execute compatibility surface, and label which one is being used.