> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harbormcp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Secret Vault

> Store API keys securely in your OS keychain and reference them in server configs.

Many MCP servers require API keys or tokens. Instead of storing these as plain text in config files, Harbor lets you store them in your operating system's keychain and reference them with `vault:` prefixes.

## How It Works

1. You store a secret in Harbor's vault (backed by your OS keychain)
2. You reference it in a server's environment variables or headers as `vault:SECRET_NAME`
3. When Harbor syncs to a host or the gateway resolves secrets at runtime, the actual value is injected

<Note>
  Your secrets are stored in the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). They never appear in plain-text config files.
</Note>

## CLI Usage

### Store a secret

```sh theme={null}
harbor chest set GITHUB_TOKEN ghp_xxxxxxxxxxxx
```

### Retrieve a secret

```sh theme={null}
harbor chest get GITHUB_TOKEN
```

### List all secrets

```sh theme={null}
harbor chest list
```

### Delete a secret

```sh theme={null}
harbor chest delete GITHUB_TOKEN
```

## Using Vault References

### In environment variables

Reference stored secrets in env vars with the `vault:` prefix:

```sh theme={null}
harbor dock --name my-server --command npx \
  --args @modelcontextprotocol/server-github \
  --env GITHUB_TOKEN=vault:GITHUB_TOKEN
```

In `~/.harbor/config.toml`:

```toml theme={null}
[servers.my-server.env]
GITHUB_TOKEN = "vault:GITHUB_TOKEN"
```

### In HTTP headers

Remote servers can use vault references in headers:

```toml theme={null}
[servers.github.headers]
Authorization = "Bearer vault:github_personal_access_token"
```

Harbor resolves the embedded `vault:` reference within the string, replacing `vault:github_personal_access_token` with the actual value while preserving the `Bearer ` prefix.

### In gateway configuration

The gateway token can also be a vault reference:

```toml theme={null}
[harbor]
gateway_token = "vault:gateway_token"
```

## OAuth Tokens

When you authorize an OAuth provider (e.g., `harbor dock slack`), Harbor automatically stores the tokens in the vault with keys like:

* `oauth:<provider>:access_token`
* `oauth:<provider>:refresh_token`
* `oauth:<provider>:client_id`
* `oauth:<provider>:client_secret`

Native servers reference these automatically. For example, after chartering Slack:

```toml theme={null}
[servers.slack.env]
SLACK_BOT_TOKEN = "vault:oauth:slack:access_token"
SLACK_TEAM_ID = "vault:oauth:slack:team_id"
```

You don't need to manage these manually — Harbor handles them during the OAuth flow.

## Desktop App

In the desktop app, manage secrets from the **Helm** page under the **Treasure Chest** section. You can add, view, and delete secrets through the UI.