@supaproxy/connections

Plugin package for SupaProxy MCP connection types. Connections are the bridge between SupaProxy and external tool servers using the Model Context Protocol.

Each connection plugin handles connecting to an MCP server, discovering available tools, and calling those tools during AI conversations.

Installation

npm install @supaproxy/connections

Quick start

import { registry } from '@supaproxy/connections'

// All built-in plugins are auto-registered on import.

// List available connection types
console.log(registry.types()) // ['http', 'stdio', 'authenticated']

// Test connectivity and discover tools
const http = registry.get('http')
const result = await http.test({ url: 'https://mcp.example.com/sse' })

if (result.ok) {
  console.log(`Found ${result.tools} tools: ${result.toolNames?.join(', ')}`)
}

// Establish a live connection
const connection = await http.connect({ url: 'https://mcp.example.com/sse' })

// Discover tools
console.log(connection.tools)

// Call a tool
const result = await connection.callTool('search', { query: 'hello' })

// Close the connection
await connection.close()

API reference

ConnectionPlugin

The interface every connection type must implement.

interface ConnectionPlugin {
  readonly type: string          // Unique identifier: 'http', 'stdio', etc.
  readonly name: string          // Human-readable name
  readonly description: string   // Short description
  readonly configSchema: { fields: ConfigField[] }

  test(config: Record<string, string>): Promise<TestResult>
  connect(config: Record<string, string>): Promise<McpConnection>
}

McpConnection

A live connection to an MCP server.

interface McpConnection {
  readonly tools: ToolDefinition[]
  callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>
  close(): Promise<void>
}

ToolDefinition

interface ToolDefinition {
  name: string
  description: string
  inputSchema: Record<string, unknown>
}

ToolCallResult

interface ToolCallResult {
  content: Array<{ type: string; text?: string }>
  isError: boolean
}

TestResult

interface TestResult {
  ok: boolean
  tools?: number          // Number of tools discovered
  toolNames?: string[]    // Names of discovered tools
  server?: string         // Server identifier
  error?: string          // Error message if test failed
}

ConfigField

interface ConfigField {
  name: string
  label: string
  type: 'text' | 'password' | 'select'
  required: boolean
  placeholder?: string
  helpText?: string
  options?: string[]
}

Registry methods

Method	Returns	Description
registry.list()	ConnectionPlugin[]	All registered plugins
registry.get(type)	ConnectionPlugin	Get plugin by type (throws if not found)
registry.has(type)	boolean	Check if a plugin type is registered
registry.types()	string[]	List all registered type identifiers
registry.schemas()	Array<{type, name, description, configSchema}>	Config schemas for dashboard forms
registry.register(plugin)	void	Register a custom plugin

Available plugins

Plugin	Type	Description
HTTP	http	Connects to MCP servers over HTTP (Streamable HTTP / SSE transport).
STDIO	stdio	Connects to MCP servers via standard input/output. For locally running tool servers.
Authenticated	authenticated	HTTP connection with authentication headers. Supports API key and bearer token auth for secured MCP servers.

Adding a new connection type

Create a file that implements ConnectionPlugin:

import type { ConnectionPlugin, McpConnection, TestResult } from '@supaproxy/connections'

export const myPlugin: ConnectionPlugin = {
  type: 'my-transport',
  name: 'My Transport',
  description: 'Custom MCP transport',
  configSchema: {
    fields: [
      { name: 'url', label: 'Server URL', type: 'text', required: true },
    ],
  },

  async test(config) {
    // Probe the server and discover tools
    return { ok: true, tools: 3, toolNames: ['a', 'b', 'c'] }
  },

  async connect(config) {
    // Establish a live connection
    return {
      tools: [],
      async callTool(name, args) {
        return { content: [{ type: 'text', text: 'result' }], isError: false }
      },
      async close() {
        // Cleanup
      },
    }
  },
}

Then register it:

import { registry } from '@supaproxy/connections'
import { myPlugin } from './my-plugin.js'

registry.register(myPlugin)

Contributing

See the SupaProxy contributing guide for development workflow, code standards, and PR process.

Documentation

Full documentation at docs.supaproxy.cloud.

License

MIT