GSS Server

Model Context Protocol server exposing Grey Swan Signals market stress intelligence as callable tools for AI agents.

GSS scores 30+ financial signals across 6 risk vectors to produce a composite market stress index (0-100). Data updates weekly. This server provides read-only access to pre-computed scored outputs — no raw data, no methodology.

Tools

Tool	Description	Key Output
get_vector_status	Single vector reading	score, elevated_count, signals[]
get_all_vector_scores	All vectors at once	array of vector readings
get_signal_detail	Individual signal	score, rarity, velocity, k-variants
get_elevated_signals	Signals above threshold	filtered signal list
get_signal_history	Historical signal readings	weekly-sampled time series
get_weekly_narrative	Plain-language interpretation	narrative text
get_alert_events	Recent signal-level alerts	STATUS_CROSSING, FAST_MOVER events
get_compound_alerts	Multi-signal stress patterns	VECTOR_SURGE, CONTAGION, etc.
get_movers	Signals with recent changes	crossings + fast movers
get_signal_catalog	Signal metadata schema (v1.0)	IDs, names, vectors, methods

Risk Vectors

Vector	Slug	Signals
Credit Risks	credit-risks	HY OAS, CCC Spread, IG/HY Deltas, SOFR-OIS, CP Spread
Volatility	volatility	VIX, SKEW, MOVE, Oil Shock, Yield Curve
Liquidity	liquidity	Reverse Repo, Reserves, Repo Fails, SOFR
Contagion	contagion	Yen Carry, Nikkei Drawdown, EU Sovereign, JGB-UST, CFTC JPY
Valuation	valuation	CAPE, ERP, Breadth, Inflation Expectations
Bank Stress	bank-stress	KBW/KRE, BKX Relative, BKX-KRE Divergence, Private Market

Alert Events

The alert system surfaces what changed — often more valuable than static scores:

• STATUS_CROSSING: Signal transitions upward into ALERT or CRITICAL tier
• FAST_MOVER: Signal score rises 10+ points in 7 days
• VECTOR_SURGE: 2+ signals in same vector at ALERT/CRITICAL
• CROSS_VECTOR_CONTAGION: 3+ vectors with elevated signals
• FAST_MOVER_CLUSTER: 3+ fast movers across any vectors in 7 days
• TRANSMISSION_CHAIN: Volatility + Credit Risks both elevated
• SEVERITY_MULTIPLIER: Valuation + any transmission vector elevated

Authentication

Include a Bearer token in the Authorization header:

Authorization: Bearer gss_your_api_key_here

Request a key at [email protected] with your intended use case.

Tiers

Tier	Daily Calls	Use Case
Free	100	Development and evaluation
Professional	1,000	Production integration
Enterprise	10,000	High-volume or multi-tenant

Connection

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "gss": {
      "url": "https://mcp.greyswansignals.com/sse",
      "headers": {"Authorization": "Bearer gss_your_key_here"}
    }
  }
}

Anthropic API (Remote MCP)

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    mcp_servers=[{
        "type": "url",
        "url": "https://mcp.greyswansignals.com/sse",
        "name": "gss",
        "authorization_token": "gss_your_key_here"
    }],
    messages=[{
        "role": "user",
        "content": "What is the current market stress reading and which vectors are elevated?"
    }]
)

Data Freshness

Every response includes a meta object:

{
  "data": { ... },
  "meta": {
    "last_updated": "2026-04-06",
    "update_cadence": "weekly",
    "scoring_mode": "k15",
    "source": "Grey Swan Signals — greyswansignals.com"
  }
}

GSS data updates weekly. For intraday applications, GSS provides macro regime context, not real-time signals.

Scoring

Scores use the k15 power-mapped scoring mode (production default):

• Rarity (70%): Percentile rank of current level within full historical distribution
• Velocity (30%): Percentile rank of 12-week rate of change
• k=1.5 power transform: Compresses mid-range percentiles, preserves extremes

Tier thresholds: BASELINE (0-25), WATCH (26-50), ALERT (51-75), CRITICAL (76-100).

Self-Hosting

# Install dependencies
pip install -r requirements.txt

# Initialize API keys database
python manage_keys.py init
python manage_keys.py create --label "local-test" --tier free

# Configure
cp .env.example .env
# Edit .env with paths to your GSS data

# Start server
python gss_mcp_server.py
# → INFO: Uvicorn running on http://0.0.0.0:8765

# Test
curl http://localhost:8765/health

Health Check

GET /health

Returns server status, database availability, and last data update timestamp.

---

Grey Swan Signals — greyswansignals.com