io.github.timmx7/styx-mcp-server
MCP server for Styx β intelligent AI routing across OpenAI, Anthropic, Google, and Mistral.
Ask AI about io.github.timmx7/styx-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about io.github.timmx7/styx-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
β‘ Styx
The MCP-Native AI Gateway
Route requests to any AI provider through one universal endpoint.
Self-hosted. Open source. BYOK.
What is Styx?
Styx is an open-source AI gateway that sits between your app and AI providers. Send requests to OpenAI, Anthropic, Google, or Mistral β all through one OpenAI-compatible endpoint. Bring your own API keys, self-host on your infra, and get full visibility into every request.
The first AI gateway with native MCP (Model Context Protocol) support.
from openai import OpenAI
client = OpenAI(
api_key="your-styx-api-key",
base_url="http://localhost:8080/v1", # β Only change needed
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello from Styx"}],
)
Features
- π MCP Native β Built-in MCP server. Connect Claude Code or Cursor in one command
- π Universal Routing β One OpenAI-compatible endpoint for all providers
- π€ styx:auto β Intelligent model routing: use
"model": "styx:auto"and let Styx pick the right model based on request complexity - π BYOK β Bring your own API keys, encrypted at rest (Fernet/AES)
- π Dashboard β Track requests, costs, latency per project and model
- π Fallbacks β Auto-failover between providers with circuit breakers
- π° Billing β Built-in subscription and credit-based billing (Stripe)
- π§ Semantic Cache β Similar questions return cached responses instantly
- β‘ Smart Routing β ML classifier routes to the optimal model for each request
- π³ Self-Hosted β Docker Compose, 5-minute setup
- π Secure β HMAC key hashing, Fernet encryption, rate limiting, TLS
Prerequisites
- Docker Engine 24+ and Docker Compose v2
- At least one AI provider API key (OpenAI, Anthropic, Google, or Mistral)
- Supabase account (free tier) β only for production mode (not needed for dev mode)
Quick Start
Option A: Setup Wizard (recommended)
git clone https://github.com/timmx7/styx.git
cd styx
./setup.sh # interactive wizard, generates .env
docker compose up -d --build # first build: ~15-20 min; subsequent starts: ~60s
The wizard lets you choose between:
- Dev mode β No Supabase needed, no authentication, instant start
- Production mode β Full Supabase auth, account creation, API keys
Option B: Manual Setup
git clone https://github.com/timmx7/styx.git
cd styx
cp .env.example .env
Edit .env with:
- Set
SKIP_AUTH=truefor dev mode, or configure Supabase for production - At least one AI provider key (e.g.,
OPENAI_API_KEY)
docker compose up -d --build # first build: ~15-20 min; subsequent starts: ~60s
Access Points
- Dashboard: http://localhost:3000
- API Gateway: http://localhost:8080 (direct) or https://localhost/v1 (via nginx/TLS)
- Docs API: https://localhost/api (via nginx)
Connect Claude Code
claude mcp add styx -- npx styx-mcp
Connect Cursor
Add to .cursor/mcp.json:
{
"styx": {
"command": "npx",
"args": ["styx-mcp"],
"env": { "STYX_API_KEY": "your-key" }
}
}
Send your first request
curl -X POST http://localhost:8080/v1/chat/completions \
-H "Authorization: Bearer YOUR_STYX_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "Hello from Styx"}]
}'
Dev mode: skip the
Authorizationheader β requests are accepted without an API key.
Use with any OpenAI SDK
// Node.js / TypeScript
import OpenAI from "openai";
const client = new OpenAI({
apiKey: "your-styx-key",
baseURL: "http://localhost:8080/v1",
});
# Python
from openai import OpenAI
client = OpenAI(
api_key="your-styx-key",
base_url="http://localhost:8080/v1",
)
Supported Providers
| Provider | Models | Status |
|---|---|---|
| OpenAI | gpt-4.1, gpt-4.1-mini, gpt-4o, gpt-4o-mini, o3, o4-mini | β |
| Anthropic | claude-sonnet-4, claude-3-5-sonnet, claude-3-5-haiku, claude-3-haiku | β |
| gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash | β | |
| Mistral | mistral-large, mistral-medium-3, mistral-small, codestral | β |
| Azure OpenAI | Same as OpenAI models, via Azure deployments | β |
Auto-routing: Any model matching the provider prefixes above (
gpt-*,claude-*,gemini-*,mistral-*,o3*,o4*) is routed automatically β even models released after your last config update.
Architecture
βββββββββββ ββββββββββββββββ βββββββββββββββββ
β Client ββββββΆβ Go Router ββββββΆβ AI Provider β
β (app) βββββββ (port 8080) βββββββ (OpenAI...) β
βββββββββββ ββββββββ¬ββββββββ βββββββββββββββββ
β
ββββββββΌββββββββ
β Python API β
β (port 8000) β
β Auth/Billing β
ββββββββ¬ββββββββ
β
ββββββββββββββΌβββββββββββββ
β β β
βββββββΌβββ ββββββββΌβββ βββββββΌβββ
βPostgresβ β Redis β β Next.jsβ
β (DB) β β (cache) β β (UI) β
ββββββββββ βββββββββββ ββββββββββ
Request flow:
Client request
β
βΌ
Go Router (:8080) βββΆ Cache check βββΆ HIT? Return instantly
β MISS? Continue...
βΌ
Budget check βββΆ OVER LIMIT? Block + alert
β OK? Continue...
βΌ
Route to best provider (OpenAI / Anthropic / Google / Mistral)
β
βΌ
Provider error? βββΆ Automatic fallback (circuit breaker)
β
βΌ
Response to client + log to ClickHouse + update Redis counters
Project Structure
styx/
βββ router/ # Go reverse proxy β the fast path (<10ms overhead)
βββ backend/ # Python FastAPI β auth, billing, business logic
βββ dashboard/ # Next.js + Tailwind β web dashboard
βββ classifier/ # ML request classifier (complexity scoring)
βββ cache-service/ # Semantic cache (Qdrant + sentence-transformers)
βββ sdk/ # Python & Node.js client SDKs
βββ packages/ # MCP server, gateway CLI
βββ infra/ # Docker, Helm, K8s, k6 load tests, Prometheus
βββ docker-compose.yml
Comparison
| Feature | Styx | OpenRouter | LiteLLM | Portkey |
|---|---|---|---|---|
| MCP Native | β | β | β | β |
| Self-Hosted | β | β | β | β |
| Open Source | β Apache 2.0 | β | β | β |
| Dashboard | β Full | β | Basic | β |
| BYOK | β Encrypted | β | β | β |
| Semantic Cache | β | β | β | β |
| Smart Routing | β ML | β | β | β |
| Circuit Breaker | β | β | β | β |
| One-Command Install | β | N/A | β | N/A |
Claude Code Plugin
Install the Styx plugin directly in Claude Code:
/plugin install styx@claude-plugin-directory
Or browse: /plugin > Discover > styx
This gives you /styx:setup, /styx:status, and the @styx-ops agent for managing your gateway from Claude Code.
MCP Connector
Styx includes a native MCP server. Connect it to Claude, Cursor, or any MCP-compatible client.
Local (stdio β requires npx)
Claude Code:
claude mcp add styx -- npx styx-mcp
Cursor: Add to .cursor/mcp.json:
{
"styx": {
"command": "npx",
"args": ["styx-mcp"],
"env": { "STYX_API_KEY": "your-key" }
}
}
Remote MCP Server
Connect to a hosted Styx instance without local installation:
Claude.ai / Claude Desktop:
Settings > Connectors > Add custom connector > URL: https://mcp.styxhq.com/mcp
Claude Code:
claude mcp add --transport http styx https://mcp.styxhq.com/mcp
See docs/DEPLOY_MCP_REMOTE.md for self-hosting the remote MCP server.
Examples
Check gateway health
Prompt: "Check if my AI gateway is healthy and which providers are connected" β Styx checks all provider connections, returns status and latency per provider, flags any issues.
Analyze spending
Prompt: "How much have I spent on AI APIs this month?" β Styx aggregates usage across providers, returns cost breakdown by model, shows cache savings.
Create a scoped API key
Prompt: "Create an API key for the marketing team limited to 1000 requests/day" β Styx generates a rate-limited key, returns the key and its configuration.
Contributing
We welcome contributions! Please see CONTRIBUTING.md.
License
Apache 2.0 β see LICENSE for details.
