---
name: serverswallet
description: Look up team server details and credentials (SSH keys, hosts, users, environments) from the ServersWallet API. Reveal plaintext secrets only when actually needed — every reveal is audit-logged.
---

# ServersWallet

A team wallet for server credentials. Use it instead of asking a human "which key is on that box?".

## Setup

- Base URL: https://serverswallet.com
- Auth: `Authorization: Bearer sw_…` (create a key in the web app: Settings → API keys, or the agent intro at https://serverswallet.com/intro). Recommended env var: `SERVERSWALLET_API_KEY`.
- Key scopes: legacy `read` / `write` (everything), or fine-grained `resource:action` — resources: `servers`, `credentials`, `env`, `integrations`, `audit`; actions: `read` (metadata), `reveal` (plaintext, implies read), `write` (mutate, implies read). Presets in the web UI: Read-only, Read + write, Env agent, Metadata watcher.
- Response envelope: `{ "data": … }` on success, `{ "error": { "message": … } }` on failure.

## Endpoints

| Method | Path | Notes |
| --- | --- | --- |
| GET | /api/v1/me | Validate the key; returns org, role, scopes |
| GET | /api/v1/servers | List servers; filters: `q` (name/hostname/os), `environment`, `tag`. Credentials are attached, secrets never are |
| GET | /api/v1/servers/{id} | One server with its credentials |
| POST | /api/v1/servers | Create server (write scope). Body: `{ name, hostname, sshUser?, port?, ipAddress?, publicIp?, os?, environment?, tags?, notes? }` |
| POST | /api/v1/credentials | Create credential (write scope). Body: `{ serverId, label, secretType, secret, username?, notes?, rotationDue? }` — `secret` is encrypted before storage; plaintext is never echoed back |
| GET | /api/v1/credentials/{id} | Credential metadata (no secret) |
| POST | /api/v1/credentials/{id}/reveal | The only endpoint returning the plaintext secret. Audited — pass `{ reason: "why" }` when you can |
| GET | /api/v1/audit?limit=50 | Recent audit log for your org |
| GET | /api/v1/env | List env vars (metadata only; filters: `environment`, `app`) |
| POST | /api/v1/env | Bulk upsert (write scope). Body: `{ "vars": [{ "environment", "app"?, "name", "value" }] }` — replaced values are kept as encrypted versions |
| POST | /api/v1/env/{id}/reveal | Plaintext value — audited, 60/min limit. Body: `{ "reason"?: "why" }` |
| GET | /api/v1/env/export?environment=production | **Plain dotenv text** for `eval` — see example |
| GET | /api/v1/env/diff?environment=production&compareTo=staging | Env comparison by fingerprint: only-in-A / only-in-B / differ / same (no values, no audit) |
| GET | /api/v1/integrations | Stored third-party API keys (Cloudflare, GitHub, AWS, …) — metadata only |
| POST | /api/v1/integrations/{id}/reveal | Plaintext service key — audited |
| POST | /api/v1/integrations/{id}/verify | Live-check the key against the vendor API |
| POST | /api/mcp | **MCP server** (JSON-RPC 2.0) — native tool access, see below |

## MCP server

Prefer MCP over raw REST if your client speaks it: `POST https://serverswallet.com/api/mcp` with the same Bearer key. Stateless — no session handshake required.

- `initialize` → `notifications/initialized` → `tools/list` / `tools/call` (protocol 2025-06-18 & 2024-11-05)
- Tools: `whoami`, `list_servers`, `create_server`, `reveal_credential`, `create_credential`, `list_env`, `upsert_env`, `reveal_env`, `delete_env`, `export_env`, `diff_env`, `list_integrations`, `reveal_integration`, `verify_integration`
- Write tools need a `write`-scoped key; reveals are audited the same as REST (`via: "mcp"` in the audit detail)

```bash
curl -s -X POST -H "Authorization: Bearer $SERVERSWALLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"export_env","arguments":{"environment":"production"}}}' \
  https://serverswallet.com/api/mcp
```

## Examples

```bash
# who am I, which org
curl -s -H "Authorization: Bearer $SERVERSWALLET_API_KEY" https://serverswallet.com/api/v1/me

# find a server by hostname
curl -s -H "Authorization: Bearer $SERVERSWALLET_API_KEY" "https://serverswallet.com/api/v1/servers?q=api-1"

# reveal its SSH key (audited)
curl -s -X POST -H "Authorization: Bearer $SERVERSWALLET_API_KEY" \
  -H "Content-Type: application/json" -d '{"reason":"deploy"}' \
  https://serverswallet.com/api/v1/credentials/CRED_ID/reveal

# load a whole environment into your shell / agent
eval $(curl -s -H "Authorization: Bearer $SERVERSWALLET_API_KEY" \
  "https://serverswallet.com/api/v1/env/export?environment=production")
```

## Rules

1. Never print a revealed secret into logs, commits, or chat output.
2. Reveal late and rarely — list first, reveal the one thing you need.
3. `401` → bad/revoked key. `402` → org hit its plan limit. `403` → key lacks the required scope for this call.