mastra-ai/mastra · error · Error

Server configuration not found for name

Error message

Server configuration not found for name: ${serverName}

What it means

Error thrown by MCPClient's private getServerConfig when no server configuration is registered under the requested name. Many operations (getConnectedClientForServer, tools/prompts/resources access, authentication) resolve the config by name first, so an unknown name fails fast with this message.

Solutions

1. Check the exact serverName against the keys passed to new MCPClient({ serverConfigs: {...} }) or setServers.
2. Log/inspect Object.keys of the configured servers to compare at runtime.
3. Register the missing server configuration before calling dependent APIs.
4. Guard lookups with a name check before invoking client APIs when names come from dynamic input.

Example fix

// before
const tools = await client.getToolsForServer('prod-mcp'); // typo
// after
const serverName = 'prod_mcp';
if (!(serverName in configuredServers)) throw new Error(`unknown server: ${serverName}`);
const tools = await client.getToolsForServer(serverName);

const configured = new Set(Object.keys(configuredServers));
if (!configured.has(serverName)) {
  throw new Error(`server "${serverName}" not configured. Available: ${[...configured].join(', ')}`);
}

function isConfiguredServer(name: string, configs: Record<string, MastraMCPServerDefinition>): name is keyof typeof configs & string {
  return Object.prototype.hasOwnProperty.call(configs, name);
}

When it happens

Trigger: Passing a serverName to any MCPClient API (getConnectedClientForServer, getToolsForServer, prompts/tools/resources methods, authenticateServer) that was never registered in the constructor's serverConfigs map or via setServers.

Common situations: Typo in server name; environment-specific config where a server was conditionally registered; refactoring/renaming server keys; loading config from env where a variable was missing so the entry was never added.

Related errors

• Agent ' ' (key: ' ') must have a non-empty description to…
• Cannot authenticate MCP server
• Cannot authenticate MCP server
• Mastra instance or listMCPServers method not available
• MCP_SERVER_MODERN_HTTP_OPTIONS_INCOMPATIBLE

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/634c3b427f21b43b. Report an issue: GitHub.

Appendix: source

Thrown at packages/mcp/src/client/configuration.ts:1542

  /**
   * Gets the stderr stream of a connected stdio server.
   *
   * Only available for servers using stdio transport with `stderr: 'pipe'`.
   * Returns null if the server is not connected, not using stdio, or stderr is not piped.
   *
   * @param serverName - The name of the server
   * @returns The stderr stream, or null
   */
  public getServerStderr(serverName: string): Stream | null {
    const client = this.mcpClientsById.get(serverName);
    if (!client) return null;
    return client.stderr;
  }

  private getServerConfig(serverName: string): MastraMCPServerDefinition {
    const serverConfig = this.serverConfigs[serverName];
    if (!serverConfig) {
      throw new Error(`Server configuration not found for name: ${serverName}`);
    }
    return serverConfig;
  }

  private async getOrCreateClient(name: string, config: MastraMCPServerDefinition): Promise<InternalMastraMCPClient> {
    if (this.disconnectPromise) {
      await this.disconnectPromise;
    }

    const exists = this.mcpClientsById.has(name);
    const existingClient = this.mcpClientsById.get(name);

    this.logger.debug('Checking connected client', { name, exists });

    if (exists) {
      // This is just to satisfy Typescript since technically you could have this.mcpClientsById.set('someKey', undefined);
      // Should never reach this point basically we always create a new MastraMCPClient instance when we add to the Map.
      if (!existingClient) {

View on GitHub (pinned to 75dd419e61)