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-db-health-check	Runs quick DB inventory queries (row counts and samples) to verify connectivity and schema health.

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/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.