---
title: MCP Server
path: sdks/mcp
status: published
---

# MCP Server

ScaiVault ships an MCP (Model Context Protocol) server exposing 67 typed tools — every major API operation, available to any MCP-aware LLM agent. Agents can read secrets, issue certificates, manage policies, query audit logs, and operate dynamic credentials without learning a custom client.

## Install and run

The MCP server ships in the same Python package as the SDK and CLI:

```bash
pip install scaivault
scaivault-mcp --help
```

Run with environment-based configuration:

```bash
export SCAIVAULT_URL="https://scaivault.scailabs.ai"
export SCAIVAULT_TOKEN="<bearer token>"
export SCAIVAULT_READ_ONLY=true                 # optional safety belt
export SCAIVAULT_MASK_VALUES=true               # optional: redact values in agent outputs

scaivault-mcp
```

The process speaks MCP over stdio. Plug it into Claude Desktop, Cursor, Cline, or any MCP-compliant host.

## Claude Desktop config

```json
{
  "mcpServers": {
    "scaivault": {
      "command": "scaivault-mcp",
      "env": {
        "SCAIVAULT_URL": "https://scaivault.scailabs.ai",
        "SCAIVAULT_TOKEN": "scai_live_...",
        "SCAIVAULT_READ_ONLY": "true",
        "SCAIVAULT_MASK_VALUES": "true"
      }
    }
  }
}
```

Restart Claude. `scaivault_*` tools appear in the tool picker.

## Safety controls

The server applies guardrails before any tool reaches the API. Most are env-driven so an operator can give an agent the narrowest possible window.

| Variable | Effect |
|----------|--------|
| `SCAIVAULT_READ_ONLY=true` | All write/delete tools refuse to execute. Reads still work. |
| `SCAIVAULT_MASK_VALUES=true` | Secret values returned to the agent are replaced with `••••••` markers — the agent can confirm a secret exists without seeing it. |
| `SCAIVAULT_ALLOWED_PATHS` | Comma-separated path prefixes. Reads/writes outside this list are refused. |
| `SCAIVAULT_DENIED_PATHS` | Comma-separated path prefixes that are always refused, even if `ALLOWED` covers them. |
| `SCAIVAULT_PARTNER_ID` / `SCAIVAULT_TENANT_ID` | Lock context to a specific tenant. |

Recommended starting profile for an agent: `READ_ONLY=true`, `MASK_VALUES=true`, `ALLOWED_PATHS=<one prefix>`. Loosen only as you build confidence.

The token's own scopes are also enforced on top — these env settings *narrow* what the token could do, never widen.

## Tool catalog

All tools are namespaced `scaivault_*`. Names are designed for an LLM to pick the right one without inspecting schemas closely.

### Secrets (7)

`scaivault_read_secret`, `scaivault_write_secret`, `scaivault_delete_secret`, `scaivault_list_secrets`, `scaivault_get_secret_versions`, `scaivault_rotate_secret`, `scaivault_check_expiration`.

### Secret policies (5)

`scaivault_list_secret_policies`, `scaivault_get_secret_policy`, `scaivault_create_secret_policy`, `scaivault_generate_secret_preview`, `scaivault_get_policy_types`.

### Access policies (4)

`scaivault_list_policies`, `scaivault_get_policy`, `scaivault_create_policy`, `scaivault_test_policy`.

### Rotation (3)

`scaivault_list_rotation_policies`, `scaivault_create_rotation_policy`, `scaivault_get_secrets_due_rotation`.

### Service accounts and API keys (6)

`scaivault_list_service_accounts`, `scaivault_get_service_account`, `scaivault_create_service_account`, `scaivault_update_service_account`, `scaivault_delete_service_account`, `scaivault_create_api_key`, `scaivault_list_api_keys`, `scaivault_delete_api_key`.

### PKI (8)

`scaivault_list_cas`, `scaivault_get_ca`, `scaivault_create_root_ca`, `scaivault_list_certificates`, `scaivault_get_certificate`, `scaivault_issue_certificate`, `scaivault_revoke_certificate`, `scaivault_validate_certificate`, `scaivault_check_expiring_certs`.

### ACME (5)

`scaivault_list_acme_accounts`, `scaivault_create_acme_account`, `scaivault_list_acme_orders`, `scaivault_create_acme_order`, `scaivault_complete_acme_challenge`, `scaivault_request_certificate`.

### Dynamic secrets (7)

`scaivault_list_dynamic_engines`, `scaivault_get_dynamic_engine`, `scaivault_create_dynamic_engine`, `scaivault_list_dynamic_roles`, `scaivault_create_dynamic_role`, `scaivault_generate_credentials`, `scaivault_list_leases`, `scaivault_renew_lease`, `scaivault_revoke_lease`, `scaivault_check_expiring_leases`.

### Federation (5)

`scaivault_list_federation_backends`, `scaivault_get_federation_backend`, `scaivault_create_federation_backend`, `scaivault_test_federation_backend`, `scaivault_sync_federation_backend`, `scaivault_proxy_read`.

### Subscriptions / events (4)

`scaivault_list_subscriptions`, `scaivault_get_subscription`, `scaivault_create_subscription`, `scaivault_delete_subscription`, `scaivault_list_event_types`.

### Audit (3)

`scaivault_query_audit`, `scaivault_audit_summary`, `scaivault_secret_audit_trail`, `scaivault_find_unauthorized_access`.

(67 tools total.)

## Resources

In addition to tools, the server exposes browseable resources at MCP URIs like `scaivault://secrets/{tenant}/{path}` and `scaivault://policies/{id}`. Hosts that support resource browsing (Claude Desktop's "@-mention" picker) let users point at specific objects without spelling out paths in prose.

## Prompts

A small set of prepared prompts comes with the server. Examples:

- `audit-investigation` — investigate suspicious access on a given path.
- `rotate-credential` — walk through end-to-end rotation of a specific secret.
- `migrate-from-env` — guided migration of a `.env` file into ScaiVault.

Host UI typically lists these under "prompts" or "slash commands".

## Example agent interactions

**Read with masking:**

> User: What credentials does my reporting service have access to?
> Agent (uses `scaivault_list_secrets` with prefix `integrations/`):
> "It can read `integrations/salesforce/oauth` (v3) and `integrations/stripe/api-key` (v1). Values are masked — I can't see them, only the paths and metadata."

**Investigate an outage:**

> User: Did anything weird happen around 14:30 today?
> Agent (uses `scaivault_query_audit` with the time window):
> "Three failed reads of `infra/db/primary/credentials` from `sa:report-runner` at 14:31:14, 14:31:45, 14:32:16. Each got `access_denied`. The service account isn't in any policy that covers that path — looks like a missing binding."

**Generate a credential:**

> User: I need temporary read-only Postgres access for an audit.
> Agent (uses `scaivault_generate_credentials` engine=`postgres-prod` role=`readonly` ttl=`1h`):
> "Generated lease `lease_abc`, valid for 1 hour. Connection URL is `postgresql://v_readonly_…@db.internal:5432/main`. I'll revoke it automatically when you tell me you're done, or in 1 hour."

## Self-hosting note

The MCP server is a client of the ScaiVault API — it doesn't run inside ScaiVault. You can deploy it anywhere your agent runs: on a laptop alongside Claude Desktop, in a sidecar next to a Cursor instance, or as a remote service consumed via MCP over HTTP/SSE (set `MCP_TRANSPORT=sse` and `PORT=8765`).

## What's next

- [CLI](./cli) — same operations from the shell.
- [Python SDK](./python) — from an application.
- [Cookbook](../api-guides/cookbook) — common patterns the MCP server is well-suited for.