Security Model

Security model for Ballast MCP connections.

Ballast MCP servers authenticate requests and enforce access controls. This page covers the security model.

Authentication

MCP endpoints accept two authentication methods:

API Keys

For Claude Desktop and programmatic clients:

Authorization: Bearer bk_your_api_key

API keys are:

  • Prefixed with bk_
  • Stored as bcrypt hashes (not recoverable)
  • Scoped to collection, organization, or user

JWT Tokens

For the web application’s internal MCP usage, JWT tokens work automatically through the session.

Authorization

After authentication, Ballast checks access permissions:

Collection-Scoped Keys

Most secure option. The key only works for a single collection:

  • Created in collection settings
  • Cannot access other collections
  • Recommended for Claude Desktop

Organization-Scoped Keys

Access all collections in the organization:

  • Created in organization settings
  • Admin-level access
  • Use for internal tools only

User-Scoped Keys

Include the user’s personal sources:

  • Associated with a specific user
  • Access to user’s personal source data (Gmail, personal Drive)
  • Required if searching personal sources via MCP

Tool-Level Permissions

Each MCP tool checks permissions before executing:

ToolRequired Permission
searchballast-search:read
list_documentsballast-search:read
read_documentballast-search:read
list_sourcesballast-integrations:read
trigger_syncintegration-type:execute
query_databallast-search:read

Superusers and admins bypass these checks.

Data Access

Personal Sources

Personal source data (Gmail, personal Google Drive) is only accessible when:

  1. The API key is user-scoped, AND
  2. The user has connected personal sources

Org-scoped and collection-scoped keys cannot access personal data.

Query Restrictions

Database tools enforce:

  • Read-only access (SELECT only)
  • No DDL or DML statements
  • Row limits on results

Network Security

  • All MCP endpoints use HTTPS (TLS 1.2+)
  • API keys transmitted in Authorization header
  • No credentials stored in URLs

Best Practices

Use collection-scoped keys

  • Limit exposure if key is compromised
  • One key per collection per client

Rotate keys regularly

  • Create new keys periodically
  • Revoke old/unused keys

Monitor key usage

  • Check last_used_at in dashboard
  • Audit access patterns

Secure your Claude config

  • Config file contains your API key
  • Ensure appropriate file permissions
  • Don’t share config files

Revoking Access

To revoke MCP access:

  1. Go to collection settings
  2. Find the API key
  3. Click Revoke

The key stops working immediately.