MCP Servers Documentation

MCP Server Layer Overview

The MCP server layer exposes Mastra tool registries to Model Context Protocol clients. Each server is created by a source-owned factory and enters the runtime through the active artifact loaders, not through a single central composition array in src/mastra/mcp-servers/index.ts.

The current composition flow is:

src/mastra/mcp-servers/index.ts is a barrel export. It is not the active composition point.

Factories

Each factory returns a fresh MCPServer instance with a name, version, description, and tool registry:

export function createAdminMcpServer(): MCPServer {
  return new MCPServer({
    name: 'Admin MCP Server',
    version: '1.0.0',
    description: 'Restricted MCP surface that exposes admin-only tooling for prompts, overrides, and health checks.',
    tools: adminTools,
  });
}

Environment Flags

Variable	Effect
`MASTRA_SKIP_ADMIN_MCP`	Disable the Admin MCP server.
`MASTRA_SKIP_K12_MCP`	Disable the K12 Safety MCP server.
`MASTRA_SKIP_DOCS_MCP`	Disable global and scoped documentation MCP servers.
`MASTRA_SKIP_DOCS_CHAT_WARMUP`	Skip docs-chat index warmup; does not disable MCP servers by itself.
`MASTRA_INCLUDE_REASONING_ENGINE`	Enables Reasoning Engine agents/tools/workflows/MCP when set to `true`; read by `env.includeReasoningEngine`.

The audited environment schema supports MASTRA_TARGET values k12, tap, sdac, handbook, and all. It does not include a separate reasoning-engine target in that enum. Reasoning Engine MCP availability follows env.includeReasoningEngine.

Discovery And Transport

When runtime directory routes are enabled, the runtime exposes:

curl http://localhost:4111/mcp-servers.json

The source-backed route returns JSON metadata for registered MCP servers. The audited route factory does not expose a separate /mcp-servers HTML endpoint.

MCP transport paths are owned by the Mastra runtime/APIM deployment layer. Direct runtime paths use /api/mcp/{serverId}/mcp and /api/mcp/{serverId}/sse; testing APIM prefixes those paths with /ai. The 2026-06-23 smoke confirmed /ai/api/mcp/* transport reachability, while /ai/mcp-servers.json still returns 401 through APIM and should not be used as the Replit discovery source until registry auth is reconciled.

Server Inventory

Server	Server ID	Factory	Source	Tools	Gate
Admin	`admin`	`createAdminMcpServer()`	`src/mastra/mcp-servers/admin-server.ts`	11	`MASTRA_SKIP_ADMIN_MCP`
K12 Safety	`k12-safety`	`createK12SafetyMcpServer()`	`packages/domain-k12/src/mcp-server.ts`	28	`MASTRA_SKIP_K12_MCP`
Reasoning Engine	`reasoning-engine`	`createReasoningEngineMcpServer()`	`src/mastra/mcp-servers/reasoning-engine-server.ts`	8	`MASTRA_INCLUDE_REASONING_ENGINE=true`
Docs	`docs`	`createDocsMcpServer()`	`src/mastra/mcp-servers/docs-server.ts`	4	`MASTRA_SKIP_DOCS_MCP`
K12 Docs	`k12-docs`	`createK12DocsMcpServer()`	`src/mastra/mcp-servers/domain-docs-server.ts`	4	`MASTRA_SKIP_DOCS_MCP`
SDAC Docs	`sdac-docs`	`createSdacDocsMcpServer()`	`src/mastra/mcp-servers/domain-docs-server.ts`	4	`MASTRA_SKIP_DOCS_MCP`
TAP Docs	`tap-docs`	`createTapDocsMcpServer()`	`src/mastra/mcp-servers/domain-docs-server.ts`	4	`MASTRA_SKIP_DOCS_MCP`
RE Docs	`reasoning-engine-docs`	`createReasoningEngineDocsMcpServer()`	`src/mastra/mcp-servers/domain-docs-server.ts`	4	`MASTRA_SKIP_DOCS_MCP`
Diagnostics	`diagnostics`	`createDiagnosticsMcpServer()`	`packages/diagnostics-mcp/src/server.ts`	11	Gateway token and environment approval policy
Testing Workbench	`testing-workbench`	Diagnostics service workbench composition	`apps/diagnostics-service/src/workbench-mcp.ts`	22	Gateway token and environment approval policy

The eight runtime-composed profiles account for 67 server-tool registrations. Including diagnostics (11) and testing workbench (22), the generated inventory tracks 10 profiles and 100 server-tool registrations. Reused docs tools are counted once per profile, so this is not a unique-implementation count.

Code Locations

Server factories: src/mastra/mcp-servers/** and packages/domain-k12/src/mcp-server.ts
Artifact loaders: src/mastra/artifacts/*.loader.ts and domain package loaders
Runtime merge point: apps/runtime/src/mastra-runtime.ts
Runtime registry route: packages/platform-runtime/src/server/routes/runtime-registries.routes.ts
Docs search tools: src/mastra/tools/docs-search/**
Diagnostics MCP adapter: packages/diagnostics-mcp/**
Diagnostics service workbench: apps/diagnostics-service/src/workbench-mcp.ts
Canonical generated counts: docs/internal/documentation-revival/mcp-inventory.json
Validation notes: docs/internal/documentation-revival/mcp-docs-chat-validation.md