Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supaproxy.cloud/llms.txt

Use this file to discover all available pages before exploring further.

Connection plugins define how SupaProxy connects to MCP servers and other data sources. Each connection type handles transport setup, authentication, and the test/connect lifecycle.

​
Installation

npm install @supaproxy/connections

​
ConnectionPlugin interface

interface ConnectionPlugin<TConfig = unknown> {
  /** Unique type identifier, e.g. "http", "stdio" */
  type: string;

  /** Human-readable name */
  name: string;

  /** Short description shown in the dashboard */
  description: string;

  /** Zod schema for configuration fields */
  configSchema: ZodSchema<TConfig>;

  /** Test the connection without persisting */
  test(config: TConfig): Promise<TestResult>;

  /** Establish a live connection and return a client */
  connect(config: TConfig): Promise<McpClient>;

  /** Disconnect and clean up */
  disconnect(client: McpClient): Promise<void>;
}

interface TestResult {
  success: boolean;
  tools?: ToolDefinition[];
  error?: string;
  latencyMs?: number;
}

​
Available plugins

Connects to MCP servers running as HTTP services via Streamable HTTP transport.
Config fieldTypeDescription
urlstringMCP server URL (e.g. http://localhost:3000/mcp)
import { httpConnection } from "@supaproxy/connections";

​
Test and connect lifecycle

Every connection goes through a two-phase lifecycle: 
1. Test     Validate config, attempt connection, discover tools
2. Connect  Establish persistent connection for query execution

​
Test phase

When a user saves a connection in the dashboard, the server calls plugin.test(config). This:
  • Validates the config against configSchema
  • Attempts to reach the MCP server
  • Calls tools/list to discover available tools
  • Returns the tool list and latency to the dashboard
If the test fails, the connection is saved with status disconnected and the error is displayed.

​
Connect phase

When a query arrives, the server calls plugin.connect(config) for each workspace connection. The returned McpClient is used to execute tool calls during the agent loop. After the query completes, plugin.disconnect(client) cleans up the connection.

​
Adding a custom connection

To add a new connection type (e.g. OAuth-secured transport):

​
1. Implement the interface

import { z } from "zod";
import type { ConnectionPlugin, McpClient, TestResult } from "@supaproxy/connections";

const configSchema = z.object({
  url: z.string().url(),
  clientId: z.string().min(1),
  clientSecret: z.string().min(1),
  tokenUrl: z.string().url(),
});

type OAuthConfig = z.infer<typeof configSchema>;

export const oauthConnection: ConnectionPlugin<OAuthConfig> = {
  type: "oauth",
  name: "OAuth HTTP",
  description: "MCP server with OAuth 2.0 client credentials.",
  configSchema,

  async test(config): Promise<TestResult> {
    // 1. Exchange credentials for access token
    // 2. Connect to MCP server with bearer token
    // 3. Call tools/list
    // 4. Return result
  },

  async connect(config): Promise<McpClient> {
    // Establish authenticated connection
  },

  async disconnect(client) {
    // Clean up
  },
};

​
2. Register the plugin

import { connectionRegistry } from "@supaproxy/connections";
import { oauthConnection } from "./oauth";

connectionRegistry.register(oauthConnection);
The dashboard will render the OAuth config form automatically from the Zod schema.