# GSS MCP Server

Model Context Protocol server exposing [Grey Swan Signals](https://greyswansignals.com) 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 | Signal Score, Status Level |
| `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 |

## Risk Vectors

| Vector | Slug | Signals |
|---|---|---|
| Credit Risks | `credit-risks` | High Yield OAS, CCC & Lower OAS, Investment Grade OAS, Commercial Paper Spread |
| Volatility | `volatility` | Fear Index, Tail Risk Hedging, Bond Market Volatility, Oil Prices, Yield Curve, Margin Debt Coverage |
| Liquidity | `liquidity` | Overnight Reverse Repo Level, Bank Reserve Balances, Treasury Repo Settlement Fails, Interbank Funding Stress |
| Contagion | `contagion` | JPY/USD Exchange Rate, Nikkei 225 Drawdown, Italy/Spain Spread over Bunds, JGB-UST 10Y Yield Spread, Hedge Fund Positioning in Yen Futures |
| Valuation | `valuation` | Shiller CAPE Ratio, Equity Risk Premium, S&P 500 Breadth (RSP/SPY Relative), Inflation Expectations |
| Bank Stress | `bank-stress` | Large Banks Underperformance, Regional Bank Drawdown, Private Credit Stress, Leveraged Loan ETF Drawdown |

Signal names shown are current as of the live catalog (`get_signal_catalog`) — call that tool for the authoritative, up-to-date list rather than treating this table as a static reference.

## Alert Events

The alert system surfaces **what changed** — often more valuable than static scores. "Elevated" below always means a signal scoring 51+ (ALERT or CRITICAL):

- **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 elevated
- **CROSS_VECTOR_CONTAGION**: 3+ vectors with at least one signal elevated
- **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 greyswansignals@gmail.com 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`:

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

### Anthropic API (Remote MCP)

```python
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:

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

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

**Exception**: `get_weekly_narrative` fetches the live site on every call rather than a weekly export, so its content can change between calls independent of the `meta.update_cadence` value on the response (which describes scoring data, not the narrative).

## Scoring

Every signal and vector resolves to a 0-100 Signal Score and a status tier: BASELINE (0-25), WATCH (26-50), ALERT (51-75), CRITICAL (76-100). Scoring methodology is proprietary and not exposed via this API.

## Self-Hosting

```bash
# 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](https://greyswansignals.com)*