# Hyperstrate Server

> Self-hosted enterprise AI gateway with model routing, provider orchestration, virtual keys, budgets, guardrails, evals, MCP tools, observability & SDK-compatible APIs. More Bifrost-style:

- **Type:** MCP server
- **Install:** `agentstack add mcp-hyperstrate-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Hyperstrate](https://agentstack.voostack.com/s/hyperstrate)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Hyperstrate](https://github.com/Hyperstrate)
- **Source:** https://github.com/Hyperstrate/server

## Install

```sh
agentstack add mcp-hyperstrate-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hyperstrate Server

  Self-hosted enterprise AI gateway with model routing, provider orchestration, virtual keys, budgets, guardrails, evals, MCP tools, observability, and SDK-compatible APIs.

  Route, govern, and observe production LLM traffic across hosted, self-hosted, OpenAI-compatible, Anthropic-compatible, native, streaming, async, and proxy inference flows.

  
  
  
  
  
  

---

## What Is Hyperstrate Server?

Hyperstrate Server is a self-hosted AI gateway for teams that need control over model routing, provider credentials, inference policy, spending limits, logs, prompts, evaluations, and multi-tenant access.

Pair it with [Hyperstrate Client](https://github.com/Hyperstrate/client), the Vue control plane for visually configuring providers, routers, prompts, evals, MCP tools, teams, virtual keys, SSO groups, analytics, and observability.

Use it when you want to:

- Put one gateway in front of OpenAI, Anthropic, Gemini, Mistral, Azure OpenAI, Bedrock, Groq, Cohere, Ollama, vLLM, LocalAI, Kling, or custom HTTP providers.
- Build routers from targets, pipeline features, and interceptors instead of hard-coding model selection into every app.
- Enforce request caps, cost budgets, rate limits, team access, API keys, virtual keys, and OIDC group mappings.
- Inspect each request with cost, latency, token usage, cache decisions, target selection, retries, fallbacks, tool calls, webhooks, and replay data.
- Run locally with SQLite or deploy as AWS Lambda functions backed by PostgreSQL and SQS.

## Highlights

| Area | What You Get |
| --- | --- |
| Gateway protocols | OpenAI Chat Completions, OpenAI Embeddings, Anthropic Messages, Hyperstrate native sync, streaming SSE, generic proxy |
| Router pipelines | Context trimming, caching, retry, fallback, rate limits, budgets, quality gates, semantic memory, MCP tools, rollout controls |
| Interceptors | Semantic routing, A/B tests, content filters, PII detection, prompt guard, prompt shield, team budgets |
| Governance | Organizations, users, teams, admin sessions, API keys, virtual keys, router team access, OIDC/JWKS exchange |
| Observability | Inference logs, pipeline traces, analytics, Prometheus metrics, audit logs, webhooks, CSV export, request replay |
| Evaluation | Named eval sets, exact/contains/LLM scoring, router regression runs, historical results |
| Async jobs | Local goroutine dispatcher for development, SQS dispatcher and Lambda worker for production |
| Deployment | Single local Go API, or SAM-managed API Lambda plus worker Lambda |

## Why Hyperstrate

| Need | Hyperstrate Approach |
| --- | --- |
| Own the gateway | MIT-licensed server you can run locally, in your cloud, or on AWS Lambda |
| Keep routing visible | Routers are made from targets, features, and interceptors that map directly to the client pipeline builder |
| Support existing SDKs | Provider-compatible proxy routes let OpenAI and Anthropic clients reuse the same integration point |
| Govern production traffic | Budgets, rate limits, virtual keys, team access, OIDC groups, content filters, PII handling, and prompt shields |
| Debug real requests | Pipeline traces show cache checks, interceptor decisions, target selection, retries, fallbacks, webhooks, and errors |
| Evaluate changes | Prompt/model experiments, evaluation sets, replay, feedback, and analytics live beside the runtime |

## How Hyperstrate Compares

Legend: `✓` = built in, `x` = not the product's focus, PartialN = possible, but with an important caveat below.

| Capability | Direct SDKs | OpenRouter | LiteLLM | Langfuse / LangSmith | Portkey / Helicone | Hyperstrate |
| --- | --- | --- | --- | --- | --- | --- |
| OpenAI-compatible gateway endpoint | x | ✓ | ✓ | x | ✓ | ✓ |
| Anthropic-compatible gateway endpoint | x | Partial1 | Partial2 | x | Partial3 | ✓ |
| Bring your own provider keys | ✓ | Partial4 | ✓ | x | Partial5 | ✓ |
| Self-host the gateway runtime | x | x | ✓ | x | Partial6 | ✓ |
| Route to self-hosted models | ✓ | Partial7 | ✓ | x | Partial8 | ✓ |
| Weighted, failover, retry, and budget routing | Partial9 | Partial10 | ✓ | x | ✓ | ✓ |
| Visual router and policy builder | x | x | Partial11 | x | Partial12 | ✓ |
| Teams, virtual keys, and usage budgets | x | Partial13 | ✓ | Partial14 | ✓ | ✓ |
| Request traces tied to router decisions | x | Partial15 | Partial16 | Partial17 | ✓ | ✓ |
| Prompt versions and eval runs beside the gateway | x | x | Partial18 | ✓ | Partial19 | ✓ |
| MCP tools in router pipelines | Partial20 | x | x | x | x | ✓ |
| Own database, logs, credentials, and policy config | ✓ | x | ✓ | Partial21 | Partial22 | ✓ |

Notes:

| Note | Comment |
| --- | --- |
| 1 | OpenRouter normalizes requests through its API, but Anthropic-native compatibility is not the same product shape as a self-hosted Anthropic proxy route. |
| 2 | LiteLLM supports many provider formats, but the primary proxy compatibility surface is OpenAI-style. |
| 3 | Portkey and Helicone support Anthropic integrations, but hosted gateway behavior depends on the provider and product mode. |
| 4 | OpenRouter has BYOK/provider-routing options, but the model router still runs on OpenRouter. |
| 5 | Managed gateway products can support customer provider keys, but credentials and policy still flow through their hosted control plane unless self-hosted options are used. |
| 6 | Helicone has open-source/self-hosting options; Portkey's common workflow is hosted or managed. The exact deployment model depends on product tier and edition. |
| 7 | OpenRouter can route to selected private/BYOK endpoints, but it is not a general local Ollama, vLLM, or arbitrary internal-model gateway. |
| 8 | Managed gateways can often call custom providers, but private-model support depends on deployment mode and provider integration. |
| 9 | Direct SDKs can do this only by writing and maintaining routing code in each application. |
| 10 | OpenRouter supports hosted model and provider routing, but not local tenant policy owned in your infrastructure. |
| 11 | LiteLLM has operational UI surfaces, but router design is still mainly config/proxy oriented. |
| 12 | Managed products expose routing configuration, but they are not primarily a self-hosted visual router builder paired to your database. |
| 13 | OpenRouter account and key controls are not the same as internal org/team/virtual-key governance for your own tenants. |
| 14 | Observability platforms have workspace and project access controls, but they do not usually enforce gateway spend policy in the request path. |
| 15 | OpenRouter can return routing/provider metadata, but it is not a full internal router trace with policy, team, budget, and interceptor decisions. |
| 16 | LiteLLM logging can capture proxy activity, but trace depth depends on callbacks, storage, and UI setup. |
| 17 | Langfuse and LangSmith trace application execution well; gateway-specific target selection and policy enforcement are external unless instrumented separately. |
| 18 | LiteLLM can integrate with observability and prompt tooling, but prompt/eval workflows are not the core gateway product surface. |
| 19 | Portkey and Helicone include prompt or eval-adjacent workflows, but depth varies by product and plan. |
| 20 | Direct SDKs can call MCP tools from app code, but the tools are not governed as router pipeline capabilities. |
| 21 | Langfuse can be self-hosted; LangSmith deployment depends on plan. Neither is the gateway holding provider credentials and live routing policy by default. |
| 22 | Managed gateways may offer self-hosted or enterprise deployments, but the default product experience is usually not "own every layer locally." |

## Product Surface

### Routing Runtime

- Route traffic with `round_robin`, `weighted`, `percentage`, `failover`, `random`, or `latency_based` strategies.
- Add pipeline features for token optimization, context compression, exact and semantic caching, provider prompt caching, retry, fallback, health checks, request coalescing, hedging, rate limits, budgets, cost-aware routing, structured output, response fingerprinting, semantic memory, response prefetching, and prompt-policy rollout.
- Use interceptors before target selection for semantic classification, A/B tests, content filtering, PII handling, prompt guard, prompt shield, and team budget overflow routing.
- Expose routers through SDK-friendly proxy routes so existing OpenAI and Anthropic clients can point their `baseURL` at Hyperstrate.

### Models, Prompts, And Tools

- Register provider models from a built-in catalog and configure API keys, base URLs, timeouts, key rotations, and provider-specific options.
- Manage prompt templates with `{{variable}}` interpolation, version history, previews, and restore.
- Register org-scoped MCP servers and allow routers to call approved tools during pipeline execution.
- Track conversations, messages, and async jobs alongside normal gateway traffic.

### Observability And Evaluation

- Store inference logs with model, router, virtual key, team, cost, latency, token usage, errors, feedback, and optional request/response payloads.
- Capture pipeline steps for cache checks, interceptor decisions, target selection, retries, fallbacks, quality gates, and webhook delivery.
- Analyze usage by model, router, virtual key, cache behavior, A/B variant, error class, and latency percentile.
- Group agent traffic with `X-Agent-Session-Id`, `X-Agent-Client`, and `X-Agent-Turn-Index` headers.
- Run evaluation sets against routers and compare exact, substring, or LLM-judged scores over time.

## Quick Start

### Prerequisites

- Go 1.25+
- Atlas CLI for migration commands
- `gotestsum` for `make test`
- `swag` and Node.js when regenerating Swagger/OpenAPI docs

### First-Time Setup

```bash
git clone https://github.com/Hyperstrate/server.git
cd server

cp .env.dist .env

# Recommended for stable local sessions.
openssl rand -base64 64
# Paste the value into JWT_SECRET in .env.
```

Supabase is optional for local development. You can start with the default SQLite database, then switch to Supabase/Postgres when you want a shared database or a production-like setup.

#### Database

For a fast local setup, leave `DATABASE_DSN` empty. The server uses `file:hyperstrate-dev.db?cache=shared&_fk=1`, creates `hyperstrate-dev.db`, and applies embedded SQLite migrations on startup.

For Supabase/Postgres:

1. Create or open a Supabase project.
2. Copy the Postgres connection string in URI format from the Supabase dashboard.
3. Add `sslmode=require` if the connection string does not already include it.
4. Set `DATABASE_DSN` in `.env`.

```dotenv
DATABASE_DSN=postgresql://postgres:@db..supabase.co:5432/postgres?sslmode=require
```

The app treats DSNs starting with `postgres://` or `postgresql://` as PostgreSQL. All other values are treated as SQLite paths. Runtime migrations are applied automatically, so Atlas is only required when you manually inspect, apply, or generate migration files.

For Atlas production migration commands, use `DATABASE_URL` because that is what `atlas.hcl` expects:

```bash
DATABASE_URL="postgresql://postgres:@db..supabase.co:5432/postgres?sslmode=require" make migrate-status-prod
```

#### Supabase Auth / OIDC

If you use Supabase Auth for login, the server only needs the public JWKS endpoint and the provider labels shown by the client. OAuth client IDs, OAuth secrets, Supabase anon keys, and Supabase service-role keys stay in Supabase or in the frontend environment; do not put them in this server's `.env`.

```dotenv
FRONTEND_URL=http://localhost:8080
OIDC_JWKS_URL=https://.supabase.co/auth/v1/.well-known/jwks.json
OIDC_PROVIDERS=google,github
```

`POST /auth/oidc/exchange` validates the Supabase access token against `OIDC_JWKS_URL` and returns a Hyperstrate session token signed with `JWT_SECRET`. This server expects Supabase Auth tokens signed with an asymmetric key (`ES256` or `RS256`) exposed through JWKS; legacy `HS256` Supabase JWT-secret tokens are not accepted by the JWKS validator.

Enable the matching OAuth providers in Supabase Auth, then set `OIDC_PROVIDERS` to the comma-separated provider names the client should display.

### Run Locally

```bash
go run ./cmd/api
```

The API starts on `http://localhost:8090` by default.

| URL | Purpose |
| --- | --- |
| `http://localhost:8090/healthz` | Health check |
| `http://localhost:8090/metrics` | Prometheus metrics |
| `http://localhost:8090/swagger/index.html` | Swagger UI |
| `http://localhost:8090/swagger/doc.json` | Swagger JSON |

On first launch, create the initial admin account through the client setup flow or call `POST /auth/setup`. The first user can become admin automatically, and `ADMIN_EMAIL` can force a specific email to always receive the admin role.

## Configuration

Configuration is read from `.env`, then `.env.local` as an override. When `APP_ENV=production`, dotenv files are ignored and values must come from the process environment.

| Variable | Default | Description |
| --- | --- | --- |
| `APP_ENV` | `development` | Set to `production` to require `JWT_SECRET` and skip dotenv loading |
| `PORT` | `8090` | HTTP listen port |
| `API_PUBLIC_URL` | empty | External API base URL used by generated Swagger docs |
| `DATABASE_DSN` | `file:hyperstrate-dev.db?cache=shared&_fk=1` | SQLite DSN for dev or PostgreSQL DSN for production |
| `JWT_SECRET` | insecure dev fallback | HS256 session signing secret. Required in production |
| `ADMIN_EMAIL` | empty | Email that always receives admin privileges |
| `FRONTEND_URL` | `http://localhost:8080` | Client URL used for CORS and OIDC redirects |
| `OIDC_JWKS_URL` | empty | JWKS endpoint used by `POST /auth/oidc/exchange` |
| `OIDC_PROVIDERS` | empty | Comma-separated provider labels for the client login UI |
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Default base URL for `GET /ai/discover` when no `baseUrl` query is passed |
| `LOG_RETENTION_DAYS` | `90` | Retention window for inference logs and audit logs |
| `SQS_QUEUE_URL` | empty | Enables the SQS async job dispatcher when set |
| `CACHE_BACKEND` | `memory` | Response cache backend: `memory` or `redis` |
| `RATE_LIMIT_BACKEND` | `memory` | Rate-limit backend selector; the router token bucket defaults to in-process memory |
| `CACHE_REDIS_ADDR` | `localhost:6379` | Redis address when `CACHE_BACKEND=redis` |
| `CACHE_REDIS_PREFIX` | `hs` | Optional Redis key prefix |
| `HEALTH_CHECK_INTERVAL_SECS` | `120` | Provider health probe interval |

## API Surface

Full interactive docs are available at `/swagger/index.html`. The main route groups are:

| Group | Endpoints |
| --- | --- |
| Health and metrics | `GET /healthz`, `GET /metrics` |
| Router inference | `POST /router/:id/v1/chat/completions`, `POST /router/:id/v1/messages`, `POST /router/:id/v1/embeddings`, `POST /router/:id/infer`, `POST /router/:id/infer/stream` |
| SDK proxy | `ANY /proxy/router/:id/*path`, `ANY /proxy/ai/:id/*path` |
| Router management | `/router`, `/router/:id/targets`, `/router/:id/features`, `/router/:id/interceptors`, `/router/:id/access`, `/router/:id/budget`, `/router/:id/lint`, `/router/import` |
| Models and AI | `/ai/catalog`, `/ai/discover`, `/ai/models`, `/ai/models/:id/configuration`, `/ai/models/:id/rotate-key`, `/ai/infer`, `/ai/infer/stream` |
| Async jobs | `POST /ai/jobs`, `GET /ai/jobs`, `GET /ai/jobs/:id`, `POST /ai/jobs/:id/process` |
| MCP | `/ai/mcp/servers`, `/router/:id/features/:featureId/mcp/tools` |
| Auth and tenancy | `/auth/setup`, `/auth/me`, `/auth/organizations`, `/auth/users`, `/auth/api-keys`, `/auth/virtual-keys`, `/auth/teams`, `/auth/oidc/group-mappings` |
| Analytics | `/analytics/usage`, `/analytics/models`, `/analytics/routers`, `/analytics/cache`, `/analytics/ab-test`, `/analytics/errors`, `/analytics/audit`, `/analytics/inference-logs`, `/analytics/agent-sessions` |
| Prompts and evals | `/prompts`, `/prompts/:id/versions`, `/router/evaluations`, `/router/evaluations/:evalId/run` |

### OpenAI SDK Exa

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Hyperstrate](https://github.com/Hyperstrate)
- **Source:** [Hyperstrate/server](https://github.com/Hyperstrate/server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-hyperstrate-server
- Seller: https://agentstack.voostack.com/s/hyperstrate
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.