README.md

@supabase/mcp-utils

A collection of utilities for working with the Model Context Protocol (MCP).

Installation

npm i @supabase/mcp-utils

yarn add @supabase/mcp-utils

pnpm add @supabase/mcp-utils

API

StreamTransport

If you're building an MCP client, you'll need to connect to MCP servers programmatically using a transport.

In addition to MCP's built-in transports, we also offer a StreamTransport to connect to clients with servers directly in-memory or over your own stream-based transport:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamTransport } from '@supabase/mcp-utils';
import { PostgrestMcpServer } from '@supabase/mcp-server-postgrest';

// Create a stream transport for both client and server
const clientTransport = new StreamTransport();
const serverTransport = new StreamTransport();

// Connect the streams together
clientTransport.readable.pipeTo(serverTransport.writable);
serverTransport.readable.pipeTo(clientTransport.writable);

const client = new Client(
  {
    name: 'MyClient',
    version: '0.1.0',
  },
  {
    capabilities: {},
  }
);

const server = new PostgrestMcpServer({
  apiUrl: API_URL,
  schema: 'public',
});

// Connect the client and server to their respective transports
await server.connect(serverTransport);
await client.connect(clientTransport);

A StreamTransport implements a standard duplex stream interface via ReadableStream and WritableStream:

interface StreamTransport {
  readable: ReadableStream;
  writable: WritableStream;
}

You can use pipeTo or pipeThrough to connect or transform streams. For more information, see the Web Streams API.

If your using Node.js streams, you can use their .toWeb() and .fromWeb() methods to convert to and from web standard streams.

The full interface for StreamTransport is as follows:

import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
import { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';

interface DuplexStream<T> {
  readable: ReadableStream<T>;
  writable: WritableStream<T>;
}

declare class StreamTransport
  implements Transport, DuplexStream<JSONRPCMessage>
{
  ready: Promise<void>;
  readable: ReadableStream<JSONRPCMessage>;
  writable: WritableStream<JSONRPCMessage>;
  onclose?: () => void;
  onerror?: (error: Error) => void;
  onmessage?: (message: JSONRPCMessage) => void;

  constructor();
  start(): Promise<void>;
  send(message: JSONRPCMessage): Promise<void>;
  close(): Promise<void>;
}