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

# Vault

> Securely store and manage project-scoped secrets like API keys, tokens, and credentials for use in workflows and MCP servers.

The Vault is Overcut's built-in secrets manager for **project-scoped credentials**: API keys, tokens, passwords, and connection strings used by a single project's workflows, agents, and MCP servers. Values are encrypted at rest and injected as environment variables when workflows execute. Secrets are never exposed to the LLM, only to the agent's sandbox environment.

The Vault lives inside [Project Settings](/docs/concepts/multi-project-workspaces#project-settings) at `Project → Project Settings → Project Vault`. Each project has its own independent vault. For platform-wide credentials shared across every project (such as the Claude API key used by the Claude Agent SDK), use [Workspace Secrets](/docs/reference/workspace-settings#workspace-secrets) instead.

***

## Overview

<CardGroup cols={2}>
  <Card title="Encrypted Storage" icon="lock">
    Secret values are encrypted before being stored. They cannot be read back through the UI or API, only updated or deleted.
  </Card>

  <Card title="Selective Assignment" icon="bullseye">
    Assign secrets to specific workflows, agents, and MCP servers, or make them available globally for all executions.
  </Card>

  <Card title="Environment Injection" icon="terminal">
    Secrets are injected as environment variables at runtime. Reference them in MCP server configs using <code>{"${VAR_NAME}"}</code> syntax.
  </Card>

  <Card title="LLM-Safe" icon="shield-halved">
    Secret values are never sent to the AI model. They exist only in the execution sandbox as environment variables.
  </Card>
</CardGroup>

***

## Creating a Secret

<Steps>
  <Step title="Open the Project Vault" icon="vault">
    Open the project, then go to <strong>Project Settings → Project Vault</strong>.
  </Step>

  <Step title="Add a new secret" icon="plus">
    Click <strong>New Secret</strong> and enter a name and value.
  </Step>

  <Step title="Name format" icon="font">
    Secret names must start with an uppercase letter and contain only uppercase letters, numbers, and underscores. For example: <code>API\_KEY</code>, <code>GITHUB\_TOKEN</code>, <code>DB\_PASSWORD\_PROD</code>.
  </Step>

  <Step title="Set availability" icon="globe">
    Toggle <strong>Available for All Executions</strong> to make the secret accessible to every workflow and agent automatically. When disabled, you must explicitly assign the secret to specific workflows or agents.
  </Step>
</Steps>

<Note>
  Secret values have a maximum size of 10KB. Once created, the name cannot be changed, only the value can be updated.
</Note>

***

## Assigning Secrets

Secrets can be scoped in two ways:

### Global Availability

Toggle **Available for All Executions** on a secret to inject it into every workflow run automatically. Use this for shared credentials that most workflows need, such as a third-party API key used across multiple MCP servers.

### Per-Workflow, Per-Agent, and Per-MCP Server

For secrets that should only be available to specific workflows, agents, or MCP servers:

<Steps>
  <Step title="Assign to a workflow" icon="arrow-progress">
    Open the workflow settings, scroll to the <strong>Secrets</strong> section, and add the secrets this workflow needs.
  </Step>

  <Step title="Assign to an agent" icon="user">
    Open the agent settings, scroll to the <strong>Secrets</strong> section, and add the secrets this agent needs.
  </Step>

  <Step title="Assign to an MCP server" icon="server">
    Open the MCP server settings, scroll to the <strong>Secrets</strong> section, and attach the secrets this server needs.
  </Step>
</Steps>

At runtime, Overcut merges secrets from all four sources (global secrets, workflow-assigned secrets, agent-assigned secrets, and MCP server-assigned secrets) and injects them into the execution environment.

***

## Referencing Secrets

Use the `${VAR_NAME}` syntax to reference vault secrets in MCP server configurations. At runtime, Overcut replaces each placeholder with the actual secret value.

**Example MCP server config referencing vault secrets:**

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "figma-developer-mcp", "--stdio"],
  "env": {
    "FIGMA_API_KEY": "${FIGMA_API_KEY}"
  }
}
```

When this MCP server starts, `${FIGMA_API_KEY}` is replaced with the decrypted value from the vault. The LLM never sees the actual key, only the tool interface exposed by the MCP server.

<Tip>
  Make sure the secret is either set to <strong>Available for All Executions</strong> or explicitly assigned to the MCP server (or the workflow/agent that uses it). Otherwise the placeholder will not resolve.
</Tip>

***

## Security Model

### Encryption at Rest

All secret values are encrypted before being written to the database. Decryption only happens at execution time through an internal, authenticated endpoint.

### No Read-Back

Secret values cannot be read back through the UI or API. The vault only tells you whether a value exists (`hasValue`). To change a secret, you enter the new value; you cannot view the current one.

### Audit Trail

Every vault operation (create, update, delete, toggle availability) is logged with the secret name (never the value), project ID, and the user who performed the action. Use [Audit Trail](/docs/reference/audit-trail) to review secret-change events and understand why sensitive values may be redacted or omitted from event details.

### LLM Isolation

Secrets are injected as environment variables into the agent's sandbox process. The AI model interacts with tools and APIs through those processes but never receives the secret values in its prompt or context.

### Output Filtering

Secret values are automatically filtered from tool outputs before they reach the model. If a tool accidentally returns a response containing a secret value, Overcut redacts it so the secret is never exposed in the conversation or logs.

***

## Best Practices

* **Use the vault for all credentials**: never hardcode API keys, tokens, or passwords in MCP server configs or agent instructions.
* **Prefer per-workflow/per-agent assignment** over global availability when a secret is only needed by a few workflows. This follows the principle of least privilege.
* **Use descriptive names** that make it clear what the secret is for: `DATADOG_API_KEY` is better than `KEY_1`.
* **Rotate secrets** by updating the value in the vault. All workflows and MCP servers referencing that secret will pick up the new value on their next execution. No config changes needed.

***

## Next Steps

* **[Multi-Project Workspaces](/docs/concepts/multi-project-workspaces)**: where the Project Vault fits in the workspace-vs-project boundary.
* **[MCP Servers](/docs/reference/mcp-servers)**: connect external tools to your agents and reference vault secrets in their configuration.
* **[Workspace Settings](/docs/reference/workspace-settings)**: workspace-level configuration, including Workspace Secrets.
* **[Core Building Blocks](/docs/building-blocks)**: understand how agents, actions, and triggers connect.