Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bruhsb/paperclip-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Secrets are encrypted credentials — API keys, database URLs, tokens — that agents and routines reference by name at runtime. Paperclip stores secret values using a pluggable provider model supporting local encryption, AWS Secrets Manager, GCP Secret Manager, and HashiCorp Vault. The four secret tools cover the full lifecycle: create new secrets, list existing ones by name, update metadata without touching the value, and rotate the value to a new version.
All secret tools are board-only — they require a board (human-user) API key. Agent API keys receive a 403 Forbidden response. Never embed secret values in issue descriptions, comments, or agent prompts.
Secret values are write-only. They are stored encrypted on creation and rotation, but are never returned in any API response — not in list, not in get, not after update. The list tool returns metadata only: name, provider, version, and timestamps.

List Secrets

Audit registered secrets by name — values never returned

Create Secret

Register a new encrypted credential for a company

Update Secret

Rename or re-describe a secret without changing its value

Rotate Secret

Replace a secret’s value, incrementing the version counter

​
paperclip_list_secrets

List secrets registered for a company. Returns metadata only — secret values are never included in any response.
​
companyId
string
required
Company UUID. Secrets are scoped per company.
​
limit
integer
Maximum secrets per page. Range 1–100. Defaults to 50.
​
offset
integer
Number of secrets to skip for pagination. Defaults to 0.
​
response_format
"markdown" | "json"
Output format. markdown (default) produces a human-readable list; json returns a structured envelope.
Returns: Pagination envelope { items: Secret[], total, count, offset, limit, has_more, next_offset }. Each Secret item contains: id, companyId, name, provider, externalRef, latestVersion, description, createdByAgentId, createdByUserId, createdAt, updatedAt. The value field is never present. Usage notes:
  • Use to audit which credentials are registered for a company and check their current version.
  • To rotate or update a secret, obtain its id from this tool, then call paperclip_rotate_secret or paperclip_update_secret.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
{
  "tool": "paperclip_list_secrets",
  "arguments": {
    "companyId": "00000000-0000-0000-0000-000000000000",
    "limit": 50,
    "response_format": "json"
  }
}

​
paperclip_create_secret

Create a new secret for a company. The value is stored encrypted immediately and is never returned in any subsequent response.
​
companyId
string
required
Company UUID. The secret will be scoped to this company.
​
name
string
required
Secret name — typically an environment-variable-style identifier (e.g. DATABASE_URL, OPENAI_API_KEY). Must be non-empty and unique within the company.
​
value
string
required
The secret value. Stored encrypted; never returned in any API response.
​
provider
"local_encrypted" | "aws_secrets_manager" | "gcp_secret_manager" | "vault"
Storage provider backend. Defaults to local_encrypted. Use cloud providers when the secret must also be managed externally.
​
description
string | null
Human-readable description of what this secret is used for. Pass null to store no description.
​
externalRef
string | null
External reference string, e.g. an AWS Secrets Manager ARN. Relevant when using cloud providers.
Returns: Created secret metadata: id, companyId, name, provider, externalRef, latestVersion (starts at 1), description, createdByAgentId, createdByUserId, createdAt, updatedAt. Value is never returned. Usage notes:
  • Use when registering a new credential or API key that agents will reference by name.
  • If the secret name already exists, use paperclip_rotate_secret to update its value — creating a duplicate name returns 409.
Errors:
CodeMeaningResolution
400Validation errorEnsure name and value are non-empty
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
409Secret name already existsUse paperclip_rotate_secret to update the existing secret’s value
{
  "tool": "paperclip_create_secret",
  "arguments": {
    "companyId": "00000000-0000-0000-0000-000000000000",
    "name": "DATABASE_URL",
    "value": "postgres://user:pass@host:5432/db",
    "provider": "local_encrypted",
    "description": "Primary PostgreSQL connection string"
  }
}

​
paperclip_update_secret

Update a secret’s metadata — name, description, or external reference — without changing its value. To change the value, use paperclip_rotate_secret.
​
secretId
string
required
Secret UUID. Obtain from paperclip_list_secrets.
​
name
string
New secret name. Must be non-empty if provided.
​
description
string | null
New description. Pass null to clear an existing description.
​
externalRef
string | null
New external reference (e.g. updated ARN). Pass null to clear.
Returns: Updated secret metadata: id, companyId, name, provider, externalRef, latestVersion, description, timestamps. Value is never returned. Usage notes:
  • Use when renaming a secret after a service migration, or updating its description for documentation purposes.
  • The value field is not accepted by this tool — use paperclip_rotate_secret to change the actual credential.
  • This operation is idempotent — calling it multiple times with the same values is safe.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
404Secret not foundVerify secretId with paperclip_list_secrets
{
  "tool": "paperclip_update_secret",
  "arguments": {
    "secretId": "sec_abc123",
    "description": "Updated: production PostgreSQL primary connection string"
  }
}

​
paperclip_rotate_secret

Rotate a secret to a new value, incrementing its version counter. Each call advances latestVersion by one (v1 → v2 → v3). Previous version references remain valid unless explicitly purged.
Rotation does not automatically invalidate previous versions. If downstream systems hold references to the old secret version, they will continue to use it until they are updated. Coordinate credential rotation with your deployment process to avoid service disruption.
​
secretId
string
required
Secret UUID. Obtain from paperclip_list_secrets.
​
value
string
required
New secret value. Stored encrypted; never returned in any response.
​
externalRef
string | null
Updated external reference after rotation (e.g. new ARN). Pass null to clear the existing reference.
Returns: Updated secret metadata with incremented latestVersion: id, companyId, name, provider, externalRef, latestVersion, description, timestamps. Value is never returned. Usage notes:
  • Use when rotating a compromised or expiring credential. Each call increments latestVersion.
  • To rename or update the description without changing the value, use paperclip_update_secret instead.
Errors:
CodeMeaningResolution
401Authentication failedCheck PAPERCLIP_API_KEY
403Permission deniedRequires board API key
404Secret not foundVerify secretId with paperclip_list_secrets
{
  "tool": "paperclip_rotate_secret",
  "arguments": {
    "secretId": "sec_abc123",
    "value": "postgres://user:newpass@host:5432/db"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us