# wasabi-mcp

MCP server for **Wasabi** (S3-compatible hot cloud storage). Exposes the
Wasabi **Stats API**'s bucket utilization data as an MCP tool.

<div align="center">

## MSPbots Connector

**The MCP Gateway built for MSPs: visible, controlled, and your data stays where it belongs.**

[**Get started at connect.mspbots.ai →**](https://connect.mspbots.ai)

</div>

---

MSPbots Connector gives your AI clients one MCP URL to reach your entire MSP stack (RMM, PSA, documentation, security, finance), and gives you control over who can call which tool and a record of everything that was called.

**Hosted service: [connect.mspbots.ai](https://connect.mspbots.ai)** · Free to use.

### Why Connector

![MSPbots Connector](https://stgoss.mspbots.ai/files/mcp/mspbots-mcp.png)

| | |
|---|---|
| **Visible** | Every tool call is logged: who, which vendor, when. Usage dashboard, CSV export, SIEM streaming. |
| **Controlled** | Role-based, per-tool allowlist. Deny by default. |
| **Protected** | Credentials encrypted per record. AI clients never see your vendor passwords or tokens. |
| **MSP-native** | Built for the MSP stack only: RMM, PSA, documentation, security, finance. |

### Quick start

1. **Sign up** at [connect.mspbots.ai](https://connect.mspbots.ai).
2. **Connect your vendors.** Pick from 150+ connectors and authorize each one on the vendor's own page, or bring your own API keys. No extra vendor accounts needed.
3. **Set access.** Create roles and decide which tools each role may call. Nothing is allowed until you allow it.
4. **Add your MCP URL to your AI client.** Copy the URL from your Connector dashboard into Claude, ChatGPT, Cursor, VS Code, Gemini, Codex, or any MCP-capable client.
5. **Ask your AI to do real work**, and watch every call appear in the audit log.

### Features

**Unified gateway**
- One MCP URL for all your AI clients
- 150+ connectors across the MSP stack
- Custom MCP servers supported, free
- Authorization happens on each vendor's own page; the AI never sees passwords or tokens
- Bring your own credentials: use the vendor API keys you already have
- Multiple accounts per app; connect once, reuse across AI clients
- Tool search: finds the right action for the task
- One sign-in; vendor credentials are injected behind the scenes and OAuth tokens refresh automatically

**Visibility**
- Audit log for every tool call (who, which vendor, when)
- Usage dashboard: call volume, top vendors, error rate, per-user activity
- Export audit logs to CSV, or stream to Loki, Graylog, or LogScale (SIEM)
- Optional recording of tool arguments and result summaries (off by default, enabled per organization)

**Control**
- Per-role, per-tool allowlist, deny by default
- owner / admin / member roles
- SCIM provisioning with Entra ID, Okta, JumpCloud, and Google Workspace

**Security**
- Credentials encrypted one record at a time (AES-256-GCM, per-record key)
- AI clients authenticate with OAuth 2.1 + PKCE
- Vendor responses are scanned for prompt-injection patterns and returned as structured data. This is one layer of defense, not a guarantee against every attack.
- Static egress IP for customer firewall and API allowlisting

### Pricing

**Free.**

Links: [connect.mspbots.ai](https://connect.mspbots.ai) · [mspbots.ai](https://mspbots.ai)

---

## Overview

- Stateless HTTP service. No credentials are ever persisted — each request
  supplies its own credentials via headers, used only for the lifetime of
  that single request.
- Supports concurrent requests; per-request credential isolation is done via
  Python `contextvars`, not a global/shared client instance.
- Entry points: `POST /mcp` (MCP protocol) and `GET /health` (health check).
- Default port: `8080` (configurable via `MCP_HTTP_PORT`).

## Authentication

The Wasabi Stats API (`stats.wasabisys.com`) — a separate, simpler API
from the S3-compatible object storage API — uses a single static header,
with no login/token exchange:

```
Authorization: <AccessKey>:<SecretKey>
```

The keys used must be Wasabi Root keys, or sub-user keys with an attached
billing/stats policy (`WasabiAccountStatsAccess` or
`WasabiBucketStatsAccess`) — plain storage-only keys are rejected. This is
already fully stateless by the vendor's own design; nothing is cached
across MCP calls.

### HEADER authentication parameters

| Header | Type | Required | Default | Allowed values | Description | Example |
|---|---|---|---|---|---|---|
| `X-Wasabi-Access-Key` | string | Yes | None | None | Wasabi API Access Key (must be a Root key or a key with a billing/stats permission policy) | `AGWZ1234567890ABCDEF` |
| `X-Wasabi-Secret-Key` | string | Yes | None | None | Corresponding Secret Key | `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8g9h0` |

Missing either header returns `401`:
```json
{
  "error": "Missing credentials",
  "message": "This server requires the X-Wasabi-Access-Key and X-Wasabi-Secret-Key headers",
  "required_headers": ["X-Wasabi-Access-Key", "X-Wasabi-Secret-Key"],
  "optional_headers": []
}
```

## Environment Variables

| Variable | Type | Required | Default | Description |
|---|---|---|---|---|
| `MCP_HTTP_PORT` | int | No | `8080` | HTTP listen port |
| `MCP_HTTP_HOST` | string | No | `0.0.0.0` | HTTP listen address |
| `WASABI_STATS_BASE_URL` | string | No | `https://stats.wasabisys.com` | Wasabi Stats API base URL (independent of the region where the bucket lives; fixed) |

## MCP Endpoint

- `POST /mcp` — MCP protocol (streamable HTTP transport)
- `GET /health` — health check, returns `{"status": "ok"}` (pure local probe, does not call the Wasabi API)

## Tool List

| Tool | Function | Parameters |
|---|---|---|
| `wasabi_get_bucket_utilizations` | List daily storage/API call usage records for all buckets in the account | `page_size` (optional, default 100, hard limit 100 — the per-page limit of the Wasabi Stats API itself), `page_num`, `from_date`, `to_date` (all optional) |

Responses are the vendor's raw JSON (`{"PageInfo": {...}, "Records": [...]}`), serialized compactly (no indentation, `ensure_ascii=False`) and capped at 20,000 characters — if the `Records` list would push the response past that, it is truncated with `truncated`/`truncated_field`/`original_count` markers added to the payload.

## Error Handling

On failure, tools return a JSON error envelope (as a string, not a protocol-level error) instead of raising:

```json
{"error": {"code": "upstream_error", "message": "...", "retryable": true}}
```

`code` is one of a fixed vocabulary: `not_configured`, `unauthorized`, `not_found`, `invalid_argument`, `rate_limited`, `upstream_error`. `retryable` tells the caller whether retrying is worthwhile. Empty result sets (no usage records for the requested range) are returned as a normal empty result, not as an error.

## Test Example

```bash
# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Wasabi-Access-Key: <your-access-key>" \
  -H "X-Wasabi-Secret-Key: <your-secret-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "wasabi_get_bucket_utilizations",
      "arguments": {}
    }
  }'
```

**Live-verified** (2026-07-30) against a real Wasabi account:
`wasabi_get_bucket_utilizations` called end-to-end through this running
server returned real data — 540 real bucket-utilization records across
270 pages, including real bucket names (e.g. "oraclegroup",
"centrewestib") in the `ap-southeast-2` region, with real storage/API-call
metrics.

## API Reference

- Public, no login required:
  - Overview: https://docs.wasabi.com/apidocs/wasabi-stats-api
  - Authentication: https://docs.wasabi.com/apidocs/authentication-with-wasabi-stats-api
  - This endpoint: https://docs.wasabi.com/apidocs/stats-api-get-v1standalone-bucket-utilizations

## Known Gaps

- **Scope is exactly MSPbots' 1 configured endpoint, not the vendor's full
  API surface** — the Wasabi Stats API also offers an account-level
  summary endpoint (`GET /v1/standalone/utilizations`) and per-bucket
  detail lookups by name or number; those are out of scope here. The
  Wasabi S3-compatible object storage API (bucket/object CRUD) is an
  entirely separate API and also out of scope.
- **The `region` field MSPbots also stores for this integration is not
  used by this server** — the one endpoint MSPbots actually uses (Stats
  API bucket utilizations) has a fixed base URL
  (`https://stats.wasabisys.com`) regardless of which Wasabi region a
  given bucket lives in; each returned record already includes its own
  `Region` field. `region` would only matter for direct S3-compatible
  object storage calls, which this server does not make.
- **`from`/`to` date range defaults are vendor-controlled** — if omitted,
  Wasabi defaults to "one month ago" through "today"; this server does not
  apply its own default and simply omits the parameter when not provided.