SMCP Proxy

Provides secure MCP access with OIDC authentication and path-based routing to multiple backends.

go

2

GitHub Stars

go

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ksysoev-smcp-proxy": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "mcp/sequentialthinking"
      ]
    }
  }
}

SMCP Proxy provides a secure front door for Model Context Protocol (MCP) services, adding enterprise-grade OIDC authentication and centralized access control so you can safely run multiple MCP backends behind a single, scalable proxy.

How to use

You run the server component to expose MCP backends with authentication and routing, and you run the client component locally to talk to that server. The proxy forwards authenticated MCP requests to configured backends. If authentication is enabled, clients obtain tokens from the OIDC provider and present them to the server, which validates them before routing requests to the backend.

Practical usage patterns you can follow:

Start the server with authentication disabled for initial testing, then enable OIDC when you are ready to enforce access control.
Run local or remote backends using the supported transport types, including STDIO backends for local model servers and HTTP backends for remote MCP servers.
Use the Models API to discover available MCP backends and the models they expose.

How to install

Prerequisites you need before installation:

Go 1.24 or higher
Docker (for running STDIO backends or the provided examples)
A compatible OIDC provider if you plan to enable OIDC authentication

Install and build the SMCP Proxy from source:

Build the single executable that includes both server and client functionality
Command: go build -o smcp-proxy ./cmd/smcp

If you prefer running with Docker, pull and run the image:

Pull the latest image: docker pull ghcr.io/ksysoev/smcp-proxy:main
Run the server with a mapped config: docker run -p 8080:8080 -v $(pwd)/configs:/app/configs ghcr.io/ksysoev/smcp-proxy:main server --config=/app/configs/proxy-server.yml

Configuration

Server configuration is defined in a YAML file. The configuration controls network settings, authentication mode, backends, and OIDC integration. You can enable OIDC, specify trusted issuers, set token validation rules, and configure multiple MCP backends with different transport types.

Example server backends include sequential thinking and memory MCP servers started as STDIO subprocesses. Each backend defines an identifier, a human-friendly name, a transport type, a request path, and an optional path prefix strip for clean routing. STDIO backends communicate via standard input/output and are typically started as containerized or local processes.

Key options from the typical server config:

host and port for the proxy server
read_timeout, write_timeout, and shutdown_timeout
auth mode (none or oidc)
mcp backends with IDs, names, transports, paths, and STDIO command invocations
oidc issuers, audience, and optional claims for token validation
TLS settings and metrics exposure

Troubleshooting and notes

If you enable OIDC, ensure the issuer URL is reachable and the client credentials are correctly configured. When using STDIO backends, verify that the container or process running the MCP server starts and stays healthy, and that the path mappings align with the configured routes. Check health and metrics endpoints to diagnose slow or failing routes.

Tools and endpoints overview

The proxy provides an API surface for discovering available MCP models and for routing requests to configured backends. It performs OIDC token validation on incoming requests and routes based on the request path to the correct MCP backend.

Available tools

ValidateOIDCToken

Validates OIDC tokens against configured issuers and audience, enforcing required claims when present.

ClientCredentialsFlow

Implements client credentials flow to obtain access tokens for the proxy client and manages automatic token refresh.

ProxyRouting

Routes requests to the appropriate MCP backend based on request path with optional path prefix stripping.

ModelsAPI

Provides an endpoint to discover available MCP backends and their exposed models.