mastra-ai/mastra · error · Error

MCPClientServerProxy does not support HTTP transport

Error message

MCPClientServerProxy does not support HTTP transport

What it means

startHTTP() hosts an MCP server over streamable HTTP; MCPClientServerProxy is a client wrapper around a remote server and cannot serve HTTP itself, so it always throws. The throw marks the operation as unsupported rather than silently doing nothing.

Solutions

Call startHTTP() only on real MCPServer instances
Guard with instanceof MCPClientServerProxy and skip proxies
Delete the call — the proxy's remote server is already hosted elsewhere

Example fix

// before
servers.forEach(s => s.startHTTP({ path: '/http' }));
// after
servers.filter(s => !(s instanceof MCPClientServerProxy)).forEach(s => s.startHTTP({ path: '/http' }));

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

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

Prevention

Guard transport startup with instanceof checks
Treat MCPClientServerProxy as read-only remote accessor — never host endpoints on it
Document in shared bootstrap code which server types support which transports

When it happens

Trigger: Calling startHTTP(options) on an MCPClientServerProxy — e.g. generic transport bootstrap that calls startHTTP on all registered servers.

Common situations: Uniform server startup code paths; mistaking a client proxy for a local MCPServer when wiring streamable HTTP endpoints.

Related errors

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

Appendix: source

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

        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,
      description: this.description,
      version_detail: {
        version: this.version,
        release_date: this.releaseDate,
        is_latest: this.isLatest,
      },
    };
  }

View on GitHub (pinned to 75dd419e61)