Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

feat(server): add MCP health controls (#86)

Leo92e573a93c43
diff --git a/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts b/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts
index b0d75a1ce..432675a21 100644
--- a/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts
+++ b/apps/server/src/provider/AkeruCatalogToolHandlers.test.ts
@@ -1,5 +1,5 @@
-import type { McpManager } from "@mastra/code-sdk/mcp/index";
-import type { OrchestrationCommand } from "@t3tools/contracts";
+import type { McpManager, McpServerStatus } from "@mastra/code-sdk/mcp/index";
+import { BotId, type OrchestrationCommand } from "@t3tools/contracts";
import { describe, expect, it, vi } from "vite-plus/test";
import {
@@ -7,6 +7,28 @@ import {
createAkeruPluginRuntime,
} from "./AkeruCatalogToolHandlers.ts";
+const connectedStatus: McpServerStatus = {
+ name: "search",
+ connected: true,
+ toolCount: 1,
+ toolNames: ["search_web"],
+ transport: "http",
+};
+
+function healthOptions(overrides = {}) {
+ return {
+ getRequestHealth: () => undefined,
+ recordSuccess: vi.fn(),
+ recordFailure: vi.fn(),
+ getDependencies: async () => ({
+ dependentBots: [{ id: BotId.make("bot-akeru"), name: "Akeru" }],
+ dependentRoutines: [],
+ }),
+ now: () => "2026-09-01T02:00:00.000Z",
+ ...overrides,
+ };
+}
+
const now = "2026-01-01T00:00:00.000Z";
function snapshot(
mcpServers: readonly Record<string, unknown>[] = [],
@@ -224,6 +246,80 @@ describe("Akeru catalog MCP tool handlers", () => {
expect(dispatch).toHaveBeenCalledOnce();
});
+ it("reports real request evidence instead of treating a connection as healthy", async () => {
+ const manager = { getServerStatuses: () => [connectedStatus] } as unknown as McpManager;
+ const handler = createAkeruCatalogToolHandlers(
+ manager,
+ undefined,
+ healthOptions({
+ getRequestHealth: () => ({
+ health: "failed" as const,
+ lastSuccessfulRequestAt: "2026-09-01T01:00:00.000Z",
+ lastFailedRequest: { at: "2026-09-01T01:30:00.000Z", message: "OAuth expired." },
+ }),
+ }),
+ ).GetMcpServerStatus!;
+
+ await expect(
+ handler({ input: { serverId: "search" }, emitProgress: vi.fn() }),
+ ).resolves.toEqual(
+ expect.objectContaining({
+ connectionState: "connected",
+ healthTest: "failed",
+ authenticationExpiresAt: null,
+ lastFailure: { at: "2026-09-01T01:30:00.000Z", message: "OAuth expired." },
+ dependentBots: [{ id: "bot-akeru", name: "Akeru" }],
+ dependentRoutines: [],
+ }),
+ );
+ });
+
+ it.each(["TestMcpServer", "ReconnectMcpServer"] as const)(
+ "%s records the real reconnect result",
+ async (toolId) => {
+ const reconnectServer = vi.fn(async () => connectedStatus);
+ const manager = {
+ getServerStatuses: () => [connectedStatus],
+ reconnectServer,
+ } as unknown as McpManager;
+ const recordSuccess = vi.fn();
+ const onRecovery = vi.fn();
+ const handler = createAkeruCatalogToolHandlers(
+ manager,
+ undefined,
+ healthOptions({ recordSuccess, onRecovery }),
+ )[toolId]!;
+
+ await expect(
+ handler({ input: { serverId: "search" }, emitProgress: vi.fn() }),
+ ).resolves.toEqual(expect.objectContaining({ connected: true }));
+ expect(reconnectServer).toHaveBeenCalledWith("search");
+ expect(recordSuccess).toHaveBeenCalledWith("search", "2026-09-01T02:00:00.000Z");
+ expect(onRecovery).toHaveBeenCalledOnce();
+ },
+ );
+
+ it("records and escalates a failed health test", async () => {
+ const failed = { ...connectedStatus, connected: false, error: "OAuth expired." };
+ const manager = {
+ getServerStatuses: () => [connectedStatus],
+ reconnectServer: async () => failed,
+ } as unknown as McpManager;
+ const recordFailure = vi.fn();
+ const onFailure = vi.fn();
+ const handler = createAkeruCatalogToolHandlers(
+ manager,
+ undefined,
+ healthOptions({ recordFailure, onFailure }),
+ ).TestMcpServer!;
+
+ await expect(handler({ input: { serverId: "search" }, emitProgress: vi.fn() })).rejects.toThrow(
+ "OAuth expired",
+ );
+ expect(recordFailure).toHaveBeenCalledOnce();
+ expect(onFailure).toHaveBeenCalledOnce();
+ });
+
it("removes installed plugins with the pre-change dependent view", async () => {
const dispatch = vi.fn<(command: OrchestrationCommand) => Promise<void>>(async () => undefined);
const runtime = createAkeruPluginRuntime({
diff --git a/apps/server/src/provider/AkeruCatalogToolHandlers.ts b/apps/server/src/provider/AkeruCatalogToolHandlers.ts
index 45589a7ab..1b5896d23 100644
--- a/apps/server/src/provider/AkeruCatalogToolHandlers.ts
+++ b/apps/server/src/provider/AkeruCatalogToolHandlers.ts
@@ -2,8 +2,9 @@
import * as NodeCrypto from "node:crypto";
import * as NodeFS from "node:fs";
-import type { McpManager } from "@mastra/code-sdk/mcp/index";
+import type { McpManager, McpServerStatus } from "@mastra/code-sdk/mcp/index";
import {
+ type BotId,
CommandId,
McpServerId,
type AkeruToolId,
@@ -12,6 +13,7 @@ import {
type OrchestrationCommand,
type OrchestrationReadModel,
} from "@t3tools/contracts";
+import * as DateTime from "effect/DateTime";
import {
isInstallableManifest,
@@ -49,6 +51,8 @@ const catalogManifestModules =
})
: loadNodeCatalogModules();
+import type { RequestHealthStatus } from "../subscription-auth/service.ts";
+
export interface AkeruCatalogToolHandlerInput {
readonly input: unknown;
readonly emitProgress: (summary: string) => void | Promise<void>;
@@ -56,6 +60,29 @@ export interface AkeruCatalogToolHandlerInput {
export type AkeruCatalogToolHandler = (input: AkeruCatalogToolHandlerInput) => Promise<unknown>;
+export interface AkeruMcpDependencies {
+ readonly dependentBots: ReadonlyArray<{ readonly id: BotId; readonly name: string }>;
+ readonly dependentRoutines: ReadonlyArray<string>;
+}
+
+export interface AkeruMcpHealthHandlerOptions {
+ readonly getRequestHealth: (serverId: string) => RequestHealthStatus | undefined;
+ readonly recordSuccess: (serverId: string, at: string) => void;
+ readonly recordFailure: (serverId: string, message: string, at: string) => void;
+ readonly getDependencies: (serverId: string) => Promise<AkeruMcpDependencies>;
+ readonly onFailure?: (
+ serverId: string,
+ message: string,
+ dependencies: AkeruMcpDependencies,
+ ) => void | Promise<void>;
+ readonly onRecovery?: (
+ serverId: string,
+ dependencies: AkeruMcpDependencies,
+ ) => void | Promise<void>;
+ readonly authenticationExpiresAt?: (serverId: string) => string | undefined;
+ readonly now?: () => string;
+}
+
type McpRuntimeStatus = ReturnType<McpManager["getServerStatuses"]>[number];
export interface AkeruPluginRuntimeOptions {
@@ -307,9 +334,83 @@ function requiredString(value: unknown, key: string): string {
return candidate;
}
+function requireServerStatus(mcpManager: McpManager, serverId: string): McpServerStatus {
+ const status = mcpManager.getServerStatuses().find((candidate) => candidate.name === serverId);
+ if (!status) throw new Error(`MCP server '${serverId}' is not configured for this bot.`);
+ return status;
+}
+
+async function mcpHealthStatus(
+ mcpManager: McpManager,
+ options: AkeruMcpHealthHandlerOptions,
+ serverId: string,
+ status = requireServerStatus(mcpManager, serverId),
+) {
+ const health = options.getRequestHealth(serverId);
+ const dependencies = await options.getDependencies(serverId);
+ const healthTest =
+ health?.health === "healthy" || health?.health === "recovered"
+ ? "passed"
+ : health?.health === "failed" || health?.health === "failed-first-request" || status.error
+ ? "failed"
+ : "not-run";
+ const connectionState = status.disabled
+ ? "disabled"
+ : status.authenticating
+ ? "authenticating"
+ : status.connecting
+ ? "connecting"
+ : status.connected
+ ? "connected"
+ : status.needsAuth
+ ? "authentication-required"
+ : "failed";
+ return {
+ serverId,
+ connectionState,
+ healthTest,
+ connected: status.connected,
+ transport: status.transport,
+ toolCount: status.toolCount,
+ toolNames: status.toolNames,
+ needsAuthentication: status.needsAuth ?? false,
+ authenticationExpiresAt: options.authenticationExpiresAt?.(serverId) ?? null,
+ lastSuccessfulRequestAt: health?.lastSuccessfulRequestAt ?? null,
+ lastFailure:
+ health?.lastFailedRequest ?? (status.error ? { at: null, message: status.error } : null),
+ nextRetryAt: health?.nextRetryAt ?? null,
+ dependentBots: dependencies.dependentBots,
+ dependentRoutines: dependencies.dependentRoutines,
+ };
+}
+
+async function checkMcpConnection(
+ mcpManager: McpManager,
+ options: AkeruMcpHealthHandlerOptions,
+ serverId: string,
+ emitProgress: AkeruCatalogToolHandlerInput["emitProgress"],
+ action: "Testing" | "Reconnecting",
+) {
+ requireServerStatus(mcpManager, serverId);
+ await emitProgress(`${action} MCP server '${serverId}'.`);
+ const status = await mcpManager.reconnectServer(serverId);
+ const at = options.now?.() ?? DateTime.formatIso(DateTime.nowUnsafe());
+ const dependencies = await options.getDependencies(serverId);
+ if (!status.connected) {
+ const message = status.error ?? `MCP server '${serverId}' did not connect.`;
+ options.recordFailure(serverId, message, at);
+ await options.onFailure?.(serverId, message, dependencies);
+ throw new Error(message);
+ }
+ options.recordSuccess(serverId, at);
+ await options.onRecovery?.(serverId, dependencies);
+ return mcpHealthStatus(mcpManager, options, serverId, status);
+}
+
export function createAkeruCatalogToolHandlers(
mcpManager?: McpManager,
pluginRuntime?: ReturnType<typeof createAkeruPluginRuntime>,
+ health?: AkeruMcpHealthHandlerOptions,
): Partial<Record<AkeruToolId, AkeruCatalogToolHandler>> {
const statuses = () => mcpManager?.getServerStatuses() ?? [];
return {
@@ -336,6 +437,28 @@ export function createAkeruCatalogToolHandlers(
: {}),
...(mcpManager
? {
+ ...(health
+ ? {
+ GetMcpServerStatus: async ({ input }) =>
+ mcpHealthStatus(mcpManager, health, requiredString(input, "serverId")),
+ TestMcpServer: async ({ input, emitProgress }) =>
+ checkMcpConnection(
+ mcpManager,
+ health,
+ requiredString(input, "serverId"),
+ emitProgress,
+ "Testing",
+ ),
+ ReconnectMcpServer: async ({ input, emitProgress }) =>
+ checkMcpConnection(
+ mcpManager,
+ health,
+ requiredString(input, "serverId"),
+ emitProgress,
+ "Reconnecting",
+ ),
+ }
+ : {}),
AuthenticateMcpServer: async ({ input, emitProgress }) => {
const serverId = requiredString(input, "serverId");
let authorizationUrl: string | undefined;
diff --git a/apps/server/src/provider/AkeruToolRuntime.test.ts b/apps/server/src/provider/AkeruToolRuntime.test.ts
index b43c063eb..b6627fc79 100644
--- a/apps/server/src/provider/AkeruToolRuntime.test.ts
+++ b/apps/server/src/provider/AkeruToolRuntime.test.ts
@@ -439,6 +439,30 @@ describe("AkeruToolRuntime", () => {
});
});
+ it("requires a production grant before an MCP connection test can reconnect", async () => {
+ const testConnection = vi.fn(async () => ({ connected: true }));
+ const runtime = createAkeruToolRuntime();
+ runtime.registerSession("thread-mcp-test", {
+ runtimeMode: "full-access",
+ workspaceType: "none",
+ catalogHandlers: { TestMcpServer: testConnection },
+ });
+ const execution = {
+ threadId: "thread-mcp-test",
+ toolId: "TestMcpServer" as const,
+ toolCallId: "tool-test-mcp",
+ input: { serverId: "search" },
+ approvalMode: "require-grant" as const,
+ };
+
+ await expect(runtime.execute(execution)).rejects.toThrow("requires approval");
+ expect(testConnection).not.toHaveBeenCalled();
+
+ runtime.grantApproval(execution);
+ await expect(runtime.execute(execution)).resolves.toEqual({ connected: true });
+ expect(testConnection).toHaveBeenCalledOnce();
+ });
+
it("rejects shell working directories outside both workspace boundaries", async () => {
const runtime = createAkeruToolRuntime();
const bot = workspace("cwd-bot");
diff --git a/apps/server/src/provider/AkeruToolRuntime.ts b/apps/server/src/provider/AkeruToolRuntime.ts
index 4f3a6edbf..8b7bc6377 100644
--- a/apps/server/src/provider/AkeruToolRuntime.ts
+++ b/apps/server/src/provider/AkeruToolRuntime.ts
@@ -143,6 +143,9 @@ const BACKEND_NAMES: Record<
| "GetPlugin"
| "InstallPlugin"
| "UninstallPlugin"
+ | "GetMcpServerStatus"
+ | "TestMcpServer"
+ | "ReconnectMcpServer"
| "AuthenticateMcpServer"
| "RestartMcpServers"
>,
diff --git a/apps/server/src/provider/Layers/AgentController.ts b/apps/server/src/provider/Layers/AgentController.ts
index 26ee6fb77..2a5c20a18 100644
--- a/apps/server/src/provider/Layers/AgentController.ts
+++ b/apps/server/src/provider/Layers/AgentController.ts
@@ -429,6 +429,7 @@ const make = (options?: AgentControllerLiveOptions) =>
>();
let channelRuntime: AkeruChannelRuntime | undefined;
let pluginRuntime: ReturnType<typeof createAkeruPluginRuntime> | undefined;
+ let pluginRuntimeOptions: AkeruPluginRuntimeOptions | undefined;
let botStateRuntime: AkeruBotStateRuntime | undefined;
const childWaiters = new Map<
string,
@@ -1427,6 +1428,11 @@ const make = (options?: AgentControllerLiveOptions) =>
access.memoryScopes.length > 0
? memoryHandlers(input.memoryAccess, access.memoryScopes)
: undefined;
+ const mcpManager = sessionResources.getMcpManager(key);
+ const mcpDependencies =
+ input.botId && input.botName
+ ? { dependentBots: [{ id: input.botId, name: input.botName }], dependentRoutines: [] }
+ : { dependentBots: [], dependentRoutines: [] };
const toolSession: AkeruToolSession = {
...(botId ? { botId } : {}),
...(input.botName ? { botName: input.botName } : {}),
@@ -1437,8 +1443,50 @@ const make = (options?: AgentControllerLiveOptions) =>
...(registeredMemoryHandlers ? { memoryHandlers: registeredMemoryHandlers } : {}),
...(input.botId && botStateRuntime ? { botState: botStateRuntime } : {}),
catalogHandlers: createAkeruCatalogToolHandlers(
- sessionResources.getMcpManager(key),
+ mcpManager,
pluginRuntime,
+ mcpManager
+ ? {
+ getRequestHealth: (serverId) => subscriptionAuth.mcpRequestHealth(serverId),
+ recordSuccess: (serverId, at) =>
+ subscriptionAuth.recordMcpRequestSuccess(serverId, at),
+ recordFailure: (serverId, message, at) =>
+ subscriptionAuth.recordMcpRequestFailure(serverId, message, at),
+ getDependencies: async (serverId) => {
+ const snapshot = await pluginRuntimeOptions?.readSnapshot();
+ return snapshot
+ ? {
+ dependentBots: snapshot.bots
+ .filter(
+ (bot) =>
+ bot.archivedAt === null &&
+ !bot.disabledMcpServerIds.some((id) => String(id) === serverId),
+ )
+ .map((bot) => ({ id: bot.id, name: bot.name })),
+ dependentRoutines: [],
+ }
+ : mcpDependencies;
+ },
+ onFailure: (serverId, message, dependencies) => {
+ for (const bot of dependencies.dependentBots) {
+ botInbox.ensureOpen({
+ incidentKey: `access:mcp-${serverId}:${bot.id}`,
+ kind: "connector-failure",
+ botId: bot.id,
+ botName: bot.name,
+ taskOrRoutine: `${serverId} access`,
+ lastFailure: message,
+ nextAction: `Reconnect ${serverId}, then retry its failed request.`,
+ });
+ }
+ },
+ onRecovery: (serverId, dependencies) => {
+ for (const bot of dependencies.dependentBots) {
+ botInbox.resolve(`access:mcp-${serverId}:${bot.id}`);
+ }
+ },
+ }
+ : undefined,
),
...(delegatedAccess && botId ? { billedBotId: botId } : {}),
...(delegationRuntime && botId
@@ -1913,6 +1961,7 @@ const make = (options?: AgentControllerLiveOptions) =>
return AgentController.of({
configurePluginRuntime: (input: AkeruPluginRuntimeOptions) =>
Effect.sync(() => {
+ pluginRuntimeOptions = input;
pluginRuntime = createAkeruPluginRuntime(input);
}),
configureDelegation: (input) =>
diff --git a/docs/internals/plugin-lifecycle-verification.md b/docs/internals/plugin-lifecycle-verification.md
index e80d280bf..74cdab97d 100644
--- a/docs/internals/plugin-lifecycle-verification.md
+++ b/docs/internals/plugin-lifecycle-verification.md
@@ -14,6 +14,10 @@ The lifecycle matrix does not copy runtime tests. These focused tests own the ru
- `apps/server/src/subscription-auth/snapshot.test.ts` keeps a built-in MCP detected until a real request passes, reports healthy and disabled state, and lists dependent bots.
- `apps/server/src/bot-inbox/connectorIncidents.test.ts` covers provider and MCP first-request failure, recovery, and stale dependent cleanup.
+Bot-facing MCP controls use the same session-scoped Mastra `McpManager`. `GetMcpServerStatus` returns the manager connection plus persisted request evidence. `TestMcpServer` and `ReconnectMcpServer` use the manager's real per-server reconnect result, then update the same health and inbox records. A connected manager without a completed request or connection test reports `not-run`, not healthy.
+
+Routine pausing remains an explicit dependency on the routine runtime in `t3code/routines-and-skills` commit `e77798657`. That branch owns durable connector dependencies and pause commands. Until it lands, MCP tool results return an empty `dependentRoutines` list and do not claim that a routine paused. Bind its repository and pause command at `AkeruMcpHealthHandlerOptions.getDependencies` and `onFailure`. Do not add a second routine store here.
+
Run the matrix with the catalog, schema, runtime, and validator checks. Do not call a vendor endpoint from automated tests.
## Vendor status
diff --git a/packages/contracts/src/akeruTools.test.ts b/packages/contracts/src/akeruTools.test.ts
index 0377a8221..79dcd8950 100644
--- a/packages/contracts/src/akeruTools.test.ts
+++ b/packages/contracts/src/akeruTools.test.ts
@@ -48,6 +48,15 @@ describe("Akeru tool contracts", () => {
);
expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "SearchPlugins")?.approval).toBe("none");
expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "GetPlugin")?.approval).toBe("none");
+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "GetMcpServerStatus")?.approval).toBe(
+ "none",
+ );
+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "TestMcpServer")?.approval).toBe(
+ "production",
+ );
+ expect(AKERU_TOOL_CATALOG.find((tool) => tool.id === "ReconnectMcpServer")?.approval).toBe(
+ "production",
+ );
});
it("accepts catalog-owned plugin inputs and rejects model-supplied recipes", () => {
diff --git a/packages/contracts/src/akeruTools.ts b/packages/contracts/src/akeruTools.ts
index 683f5345d..6da8705e3 100644
--- a/packages/contracts/src/akeruTools.ts
+++ b/packages/contracts/src/akeruTools.ts
@@ -75,6 +75,9 @@ export const AkeruToolId = Schema.Literals([
"GetPlugin",
"InstallPlugin",
"UninstallPlugin",
+ "GetMcpServerStatus",
+ "TestMcpServer",
+ "ReconnectMcpServer",
"UpdateBotProfile",
"AuthenticateMcpServer",
"RestartMcpServers",
@@ -148,6 +151,9 @@ export const AkeruToolInputSchemas = {
GetPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),
InstallPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),
UninstallPlugin: Schema.Struct({ pluginId: TrimmedNonEmptyString }),
+ GetMcpServerStatus: McpServerIdInput,
+ TestMcpServer: McpServerIdInput,
+ ReconnectMcpServer: McpServerIdInput,
UpdateBotProfile: UpdateBotProfileInput,
AuthenticateMcpServer: McpServerIdInput,
RestartMcpServers: Schema.Struct({
@@ -298,6 +304,13 @@ export const AKERU_TOOL_CATALOG = [
define("UninstallPlugin", "bot-workspace", "Remove a curated plugin after inspecting it.", {
approval: "delete",
}),
+ define("GetMcpServerStatus", "bot-workspace", "Inspect an MCP server connection."),
+ define("TestMcpServer", "bot-workspace", "Run a real MCP server connection test.", {
+ approval: "production",
+ }),
+ define("ReconnectMcpServer", "bot-workspace", "Reconnect one MCP server.", {
+ approval: "production",
+ }),
define("UpdateBotProfile", "bot-workspace", "Update this bot's public profile."),
define("AuthenticateMcpServer", "bot-workspace", "Authenticate an MCP server.", {
approval: "secrets",