mcpproxy

package module

v1.1.0 Latest Latest Go to latest Published: Sep 22, 2025 License: MIT Imports: 24 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/shyarora/mcp-proxy

Links

Open Source Insights

README ¶

MCP Proxy Server

An MCP proxy that aggregates multiple MCP servers behind a single HTTP entrypoint.

This is a Go library for integration into other projects.

Features

Proxy multiple MCP clients: aggregate tools, prompts, and resources from many servers.
SSE and streamable HTTP: serve via Server‑Sent Events or streamable HTTP.
Flexible config: supports stdio, sse, and streamable-http client types.
Library Support: Can be imported and used as a Go library in other projects.

Documentation

Configuration: docs/configuration.md
Usage: docs/usage.md
Deployment: docs/deployment.md
Library Usage: LIBRARY_USAGE.md
Claude config converter: https://tbxark.github.io/mcp-proxy

Quick Start

As a Go Library

go get github.com/shyarora/mcp-proxy

import mcpproxy "github.com/shyarora/mcp-proxy"

opts := mcpproxy.ProxyOptions{
    ConfigPath:  "config.json",
    ExpandEnv:   true,
    HTTPTimeout: 10,
}
err := mcpproxy.RunProxy(opts)

See LIBRARY_USAGE.md for detailed library documentation.

Configuration

See full configuration reference and examples in docs/configuration.md. An online Claude config converter is available at: https://tbxark.github.io/mcp-proxy

Usage

Library usage examples and API documentation are documented in LIBRARY_USAGE.md.

Thanks

This project was inspired by the adamwattis/mcp-proxy-server project
If you have any questions about deployment, you can refer to 《在 Docker 沙箱中运行 MCP Server》(@ccbikai)

License

This project is licensed under the MIT License. See the LICENSE file for details.

Documentation ¶

Index ¶

Constants
func RunProxy(opts ProxyOptions) error
func StartServer(config *ProxyConfig) error
func StartServerWithContext(ctx context.Context, config *ProxyConfig) error
type Client
- func (c *Client) Close() error
type Config
type MCPClientConfigV2
type MCPClientType
type MCPProxyConfigV2
type MCPServerType
type MiddlewareFunc
type OptionsV2
type ProxyConfig
- func LoadConfig(configPath string, insecure, expandEnv bool, httpHeaders string, ...) (*ProxyConfig, error)
type ProxyOptions
- func NewDefaultProxyOptions() ProxyOptions
type SSEMCPClientConfig
type Server
type StdioMCPClientConfig
type StreamableMCPClientConfig
type ToolFilterConfig
type ToolFilterMode

Constants ¶

View Source

const (
	DefaultConfigPath  = "config.json"
	DefaultExpandEnv   = true
	DefaultHTTPTimeout = 10
	DefaultInsecure    = false
	DefaultHTTPHeaders = ""
)

Default values for proxy options

Variables ¶

This section is empty.

Functions ¶

func RunProxy ¶

func RunProxy(opts ProxyOptions) error

RunProxy is a convenience function that combines LoadConfig and StartServer. This is useful for simple use cases where you want to start the proxy with minimal setup.

Parameters:

opts: the proxy options (equivalent to command-line flags)

Returns an error if configuration loading or server startup fails.

func StartServer ¶

func StartServer(config *ProxyConfig) error

StartServer starts the HTTP server with the provided configuration. This function blocks until the server is shut down or an error occurs.

The server will listen for shutdown signals (SIGINT, SIGTERM) and gracefully shutdown.

Parameters:

config: the proxy configuration loaded from LoadConfig

Returns an error if the server fails to start or encounters an error during operation.

func StartServerWithContext ¶

func StartServerWithContext(ctx context.Context, config *ProxyConfig) error

StartServerWithContext starts the HTTP server with the provided configuration and context. This allows for more fine-grained control over server lifecycle.

Parameters:

ctx: context for controlling server lifecycle
config: the proxy configuration loaded from LoadConfig

Returns an error if the server fails to start or encounters an error during operation.

Types ¶

type Client ¶

type Client struct {
	// contains filtered or unexported fields
}

func (*Client) Close ¶

func (c *Client) Close() error

type Config ¶

type Config struct {
	McpProxy   *MCPProxyConfigV2             `json:"mcpProxy"`
	McpServers map[string]*MCPClientConfigV2 `json:"mcpServers"`
}

type MCPClientConfigV2 ¶

type MCPClientConfigV2 struct {
	TransportType MCPClientType `json:"transportType,omitempty"`

	// Stdio
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`

	// SSE or Streamable HTTP
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
	Timeout time.Duration     `json:"timeout,omitempty"`

	Options *OptionsV2 `json:"options,omitempty"`
}

type MCPClientType ¶

type MCPClientType string

const (
	MCPClientTypeStdio      MCPClientType = "stdio"
	MCPClientTypeSSE        MCPClientType = "sse"
	MCPClientTypeStreamable MCPClientType = "streamable-http"
)

type MCPProxyConfigV2 ¶

type MCPProxyConfigV2 struct {
	BaseURL string        `json:"baseURL"`
	Addr    string        `json:"addr"`
	Name    string        `json:"name"`
	Version string        `json:"version"`
	Type    MCPServerType `json:"type,omitempty"`
	Options *OptionsV2    `json:"options,omitempty"`
}

type MCPServerType ¶

type MCPServerType string

const (
	MCPServerTypeSSE        MCPServerType = "sse"
	MCPServerTypeStreamable MCPServerType = "streamable-http"
)

type MiddlewareFunc ¶

type MiddlewareFunc func(http.Handler) http.Handler

type OptionsV2 ¶

type OptionsV2 struct {
	PanicIfInvalid optional.Field[bool] `json:"panicIfInvalid,omitempty"`
	LogEnabled     optional.Field[bool] `json:"logEnabled,omitempty"`
	AuthTokens     []string             `json:"authTokens,omitempty"`
	ToolFilter     *ToolFilterConfig    `json:"toolFilter,omitempty"`
}

type ProxyConfig ¶

type ProxyConfig struct {
	McpProxy   *MCPProxyConfigV2             `json:"mcpProxy"`
	McpServers map[string]*MCPClientConfigV2 `json:"mcpServers"`
}

ProxyConfig represents the main configuration for the MCP proxy

func LoadConfig ¶

func LoadConfig(configPath string, insecure, expandEnv bool, httpHeaders string, httpTimeout int) (*ProxyConfig, error)

LoadConfig loads the configuration from a file or URL with the specified options. This is the public API function that external libraries can use.

Parameters:

configPath: path to config file or HTTP(S) URL
insecure: allow insecure HTTPS connections by skipping TLS certificate verification
expandEnv: expand environment variables in config file
httpHeaders: optional HTTP headers for config URL, format: 'Key1:Value1;Key2:Value2'
httpTimeout: HTTP timeout in seconds when fetching config from URL

Returns the loaded configuration or an error.

type ProxyOptions ¶

type ProxyOptions struct {
	ConfigPath  string
	Insecure    bool
	ExpandEnv   bool
	HTTPHeaders string
	HTTPTimeout int
}

ProxyOptions represents the command-line options that can be used when starting the proxy

func NewDefaultProxyOptions ¶

func NewDefaultProxyOptions() ProxyOptions

NewDefaultProxyOptions creates a ProxyOptions struct with default values

type SSEMCPClientConfig ¶

type SSEMCPClientConfig struct {
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers"`
}

type Server ¶

type Server struct {
	// contains filtered or unexported fields
}

type StdioMCPClientConfig ¶

type StdioMCPClientConfig struct {
	Command string            `json:"command"`
	Env     map[string]string `json:"env"`
	Args    []string          `json:"args"`
}

type StreamableMCPClientConfig ¶

type StreamableMCPClientConfig struct {
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers"`
	Timeout time.Duration     `json:"timeout"`
}

type ToolFilterConfig ¶

type ToolFilterConfig struct {
	Mode ToolFilterMode `json:"mode,omitempty"`
	List []string       `json:"list,omitempty"`
}

type ToolFilterMode ¶

type ToolFilterMode string

const (
	ToolFilterModeAllow ToolFilterMode = "allow"
	ToolFilterModeBlock ToolFilterMode = "block"
)

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL