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.

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)

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.