# Failsafe MCP Server

**Credential resilience for AI agents.**

Your agent runs on 50+ credentials. Failsafe makes sure they never break.

- 🔑 **Store** credentials with AES-256 encryption
- 🏥 **Monitor** health with automatic provider-specific checks
- 🔀 **Failover** to backup credentials when primary fails
- ⏰ **Warn** before credentials expire
- 🔌 **MCP native** — works with Claude Code, Cursor, LangChain, and any MCP client

## Quick Start

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "failsafe": {
      "command": "npx",
      "args": ["-y", "failsafe-mcp-server"]
    }
  }
}
```

### With Claude Code

```bash
claude mcp add failsafe -- npx -y failsafe-mcp-server
```

### Manual

```bash
npm install -g failsafe-mcp-server
failsafe-mcp-server
```

## What It Does

### Store a credential

```
> failsafe_store provider:"openai" key:"sk-abc123" backup_key:"sk-xyz789"

✓ Credential stored for openai. Backup configured.
```

### Get a credential (with auto-failover)

```
> failsafe_get provider:"openai"

{
  "key": "sk-abc123",
  "source": "primary",
  "status": "healthy"
}
```

If the primary key is unhealthy, Failsafe automatically returns the backup:

```
> failsafe_get provider:"openai"

{
  "key": "sk-xyz789",
  "source": "backup",
  "warnings": ["Primary credential is unhealthy. Using backup."]
}
```

### List all credentials

```
> failsafe_list

{
  "summary": { "total": 4, "healthy": 3, "unhealthy": 1, "expired": 0 },
  "credentials": [
    { "provider": "openai", "status": "healthy", "has_backup": true },
    { "provider": "anthropic", "status": "healthy", "has_backup": false },
    { "provider": "github", "status": "unhealthy", "has_backup": true },
    { "provider": "stripe", "status": "healthy", "has_backup": false }
  ]
}
```

### Run health checks

```
> failsafe_health

{
  "summary": { "total": 4, "healthy": 3, "unhealthy": 1 },
  "results": [
    { "provider": "openai", "status": "healthy", "latency_ms": 245 },
    { "provider": "anthropic", "status": "healthy", "latency_ms": 189 },
    { "provider": "github", "status": "unhealthy", "response_code": 401 },
    { "provider": "stripe", "status": "healthy", "latency_ms": 312 }
  ]
}
```

## Supported Providers

Built-in health checks for:

| Provider | Health Check Endpoint |
|----------|----------------------|
| OpenAI | `GET /v1/models` |
| Anthropic | `GET /v1/models` |
| GitHub | `GET /user` |
| Stripe | `GET /v1/balance` |

Any other provider works with a custom `health_check_url`:

```
> failsafe_store provider:"my-saas" key:"token_abc" health_check_url:"https://api.my-saas.com/health"
```

## Security

- All credentials encrypted with **AES-256-GCM** at rest
- Master key auto-generated and stored in `~/.failsafe/master.key` (mode 0600)
- Or set `FAILSAFE_MASTER_KEY` environment variable
- **100% local** — credentials never leave your machine
- No telemetry, no network calls except health checks to your own providers

## How Failover Works

```
Agent requests credential for "openai"
  ↓
Failsafe checks primary key status
  ↓
├─ Healthy? → return primary key
├─ Unhealthy/Expired? → check for backup
│   ├─ Backup exists? → return backup key + warning
│   └─ No backup? → return primary key + warning
```

## Data Storage

All data stored locally in `~/.failsafe/`:

```
~/.failsafe/
├── master.key         # Encryption key (auto-generated)
└── credentials.json   # Encrypted credential store
```

## Roadmap

- [x] Store / Get / List / Remove credentials
- [x] AES-256-GCM encryption
- [x] Health checks (OpenAI, Anthropic, GitHub, Stripe + custom)
- [x] Automatic failover (primary → backup)
- [x] Expiration warnings
- [ ] Background health monitoring (cron)
- [ ] Multi-key rotation / load balancing
- [ ] Webhook notifications (Slack, Telegram)
- [ ] Failsafe Cloud (hosted dashboard + team management)

## License

MIT

## Links

- Website: [failsafe.world](https://failsafe.world)
- GitHub: [github.com/sunglc/failsafe-mcp-server](https://github.com/sunglc/failsafe-mcp-server)
- Twitter: [@climber_sun](https://x.com/climber_sun)