mastra-ai/mastra · error · Error

MCPClientServerProxy does not support stdio transport

Error message

MCPClientServerProxy does not support stdio transport

What it means

MCPClientServerProxy wraps a remote MCP client and intentionally does not implement server-side transports. Calling startStdio() throws because a client proxy never hosts a stdio server; stdio only applies to Mastra MCPServer instances serving tools locally.

Source

Thrown at packages/mcp/src/client/server-proxy.ts:194

      })),
    };
  }

  public async readResource(uri: string): Promise<{ contents: Array<{ uri: string; text?: string; blob?: string }> }> {
    const client = await this.getClient();
    const result = await client.resources.read(uri);
    return {
      contents: (result.contents ?? []).map((c: any) => ({
        uri: c.uri ?? uri,
        ...(c.text !== undefined ? { text: c.text } : {}),
        ...(c.blob !== undefined ? { blob: c.blob } : {}),
      })),
    };
  }

  // Transport methods — not applicable for client proxies
  public async startStdio(): Promise<void> {
    throw new Error('MCPClientServerProxy does not support stdio transport');
  }
  public async startSSE(_options: MCPServerSSEOptions): Promise<void> {
    throw new Error('MCPClientServerProxy does not support SSE transport');
  }
  public async startHonoSSE(_options: MCPServerHonoSSEOptions): Promise<Response | undefined> {
    throw new Error('MCPClientServerProxy does not support Hono SSE transport');
  }
  public async startHTTP(_options: MCPServerHTTPOptions): Promise<void> {
    throw new Error('MCPClientServerProxy does not support HTTP transport');
  }
  public async close(): Promise<void> {
    this.cachedClient = null;
  }

  public getServerInfo(): ServerInfo {
    return {
      id: this.id,
      name: this.name,

View on GitHub (pinned to 75dd419e61)

Solutions

Only call startStdio() on actual MCPServer instances, not MCPClientServerProxy
Type-check or instanceof-check the object before calling transport methods
Remove the startStdio call — client proxies are already connected via getClient()

Example fix

// before
for (const s of registry.getAll()) await s.startStdio();
// after
for (const s of registry.getAll()) {
  if (!(s instanceof MCPClientServerProxy)) await s.startStdio();
}

Defensive patterns

Strategy: validation

Validate before calling

if (proxy instanceof MCPClientServerProxy) throw new Error('startStdio is only valid on MCPServer instances');

Type guard

function isRealServer(s: unknown): s is MCPServer {
  return !(s instanceof MCPClientServerProxy);
}

Try / catch

try {
  await maybeServer.startStdio();
} catch (e) {
  if (e instanceof Error && e.message.includes('does not support stdio transport')) return;
  throw e;
}

Prevention

Distinguish MCPClient proxies from MCPServer instances in registry code
Use instanceof checks before calling transport methods
Remember client proxies connect lazily via getClient(); no start needed

When it happens

Trigger: Calling startStdio() on an MCPClientServerProxy instance obtained from MCPClients registry (e.g. iterating servers and calling transport start methods uniformly).

Common situations: Generic code that starts every server in a registry without distinguishing real MCPServer instances from client proxies; copy-pasting server bootstrap code onto proxy objects.

Related errors

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