Skip to content
Guides
/
/
Claude Cowork
Last updated

Claude Cowork Integration

Connect Claude Cowork to Capsule Security for complete visibility into Claude AI activity, including user prompts, tool execution, model API calls, errors, and session lifecycle. This integration uses Claude's native OpenTelemetry (OTLP) logs exporter — no hooks, scripts, or custom binaries required.

Overview

Claude emits structured telemetry as OpenTelemetry log records. Capsule provisions a dedicated OTLP endpoint and a long-lived bearer token scoped to your tenant, which Claude can be configured to export to via standard OTEL environment variables.

The following events are captured:

OTEL EventDescription
user_promptUser prompts submitted to Claude
tool_resultTool execution results, including MCP tool invocations
api_requestModel API requests with token usage, duration, and cost
api_errorModel API errors
tool_decisionTool permission decisions (allow / deny / source)
session_startSession initialization

Each event is correlated to an agent identified by user email or user ID, and entities (working directories, tools, MCP servers, models) are materialized automatically into your inventory.

Prerequisites

Before you begin, ensure you have:

  • Claude Cowork enabled for your organization
  • A Capsule Security account with admin access
  • Permission to set environment variables on developer machines (locally, via shell profile, or via MDM)

Step 1: Generate the OTLP Configuration

  1. Log in to the Capsule Security portal

  2. Navigate to Integrations and locate Claude Cowork

  3. Click Install — Capsule generates an OTLP configuration containing:

    • The OTLP HTTP/JSON endpoint URL scoped to your tenant
    • A bearer token (JWT) embedding your tenant, environment, and platform IDs
    • The transport protocol (http/json)

    The token is valid for 365 days and binds telemetry to a single environment in your tenant. Treat it as a secret.

  4. Copy the three values shown in the portal:

    • endpoint — e.g. https://otel.capsule.security/v1/claude-cowork/otel/v1/logs
    • protocol — http/json
    • authorizationHeader — Bearer <jwt>

Step 2: Configure Claude to Export Telemetry

Claude reads OTEL configuration from standard OpenTelemetry environment variables. Set the following on each machine running Claude:

VariableValue
CLAUDE_CODE_ENABLE_TELEMETRY1
OTEL_LOGS_EXPORTERotlp
OTEL_EXPORTER_OTLP_PROTOCOLhttp/json
OTEL_EXPORTER_OTLP_ENDPOINTThe endpoint from Step 1 (without the /v1/logs suffix if your client appends it; otherwise paste the full URL)
OTEL_EXPORTER_OTLP_HEADERSAuthorization=Bearer <jwt>

Note: Claude exports OTLP logs to the path /v1/logs relative to OTEL_EXPORTER_OTLP_ENDPOINT. The Capsule endpoint already includes the full path — set OTEL_EXPORTER_OTLP_ENDPOINT to the exact URL Capsule provided.

Local Setup (Single Developer)

Add the variables to your shell profile (~/.zshrc, ~/.bashrc, or equivalent):

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel.capsule.security/v1/claude-cowork/otel/v1/logs"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer eyJhbGciOiJIUzI1NiIs..."

Reload your shell (source ~/.zshrc) and restart Claude.

Enterprise Rollout (MDM)

For organization-wide deployment, distribute the environment variables via your MDM solution:

PlatformRecommended Mechanism
macOSConfiguration Profile setting EnvironmentVariables, or launchctl setenv via Jamf/Kandji preinstall script
Linux/etc/environment or /etc/profile.d/claude-otel.sh deployed via Ansible / Salt / Intune
WindowsGroup Policy → User Configuration → Preferences → Windows Settings → Environment, or Intune Configuration Profile

Refer to the Jamf Pro, Kandji, Intune, SCCM, and Tanium guides for platform-specific deployment patterns.

Security: The bearer token grants write access to your Capsule telemetry endpoint. Distribute it via your MDM's secure variable mechanism, never commit it to version control, and rotate it from the Capsule portal if it is exposed.

Step 3: Restart Claude

For the OTEL exporter to pick up the new configuration:

  1. Exit Claude
  2. Open a new shell session (so the updated environment variables are loaded)
  3. Start Claude

Step 4: Verify the Installation

  1. Run a simple prompt in Claude to generate activity, for example:

    List the files in the current directory.

  2. Log in to the Capsule Security portal

  3. Navigate to Inventory > Agents and confirm a new agent appears named Cowork/<username> (derived from the user's email)

  4. Click the agent to review:

    • Audit logs — user prompts, tool invocations, API requests, errors, session lifecycle
    • Entities — working directories, tools, MCP servers, models
    • Owner — mapped from the OTEL user.email attribute

  5. To inspect full conversations, navigate to Observability and filter by Activity Type — Session

What to Expect

ResourceHow It's Created
AgentOne per unique user.email (or user.id), named Cowork/<email-prefix>
Owner (User)Mapped from user.email — appears in the agent's Owner column
Working Directory entitiesOne per path in workspace.host_paths
Tool entitiesOne per built-in tool used (Bash, Read, Edit, etc.)
MCP Tool entitiesOne per <mcp_server_name>:<mcp_tool_name> combination, tagged with protocol MCP
Model entitiesOne per Claude model invoked (e.g., claude-opus-4-7)

Troubleshooting

If events are not appearing in Capsule:

  1. Confirm telemetry is enabled — CLAUDE_CODE_ENABLE_TELEMETRY=1 must be set in the same shell environment Claude runs in. Run echo $CLAUDE_CODE_ENABLE_TELEMETRY in the terminal where Claude is launched.

  2. Verify the endpoint and headers — echo $OTEL_EXPORTER_OTLP_ENDPOINT and echo $OTEL_EXPORTER_OTLP_HEADERS should match the values from the Capsule portal exactly.

  3. Check network connectivity — from the developer machine, the OTEL endpoint must be reachable:

    curl -i -X POST "$OTEL_EXPORTER_OTLP_ENDPOINT" \
  -H "Content-Type: application/json" \
  -H "$OTEL_EXPORTER_OTLP_HEADERS" \
  -d '{"resourceLogs":[]}'

    A 200 or 204 response confirms the token is valid. A 401 indicates the token is malformed or expired — regenerate it from the portal.

  4. Confirm the user has an email — agent identity is derived from user.email. If only user.id is present in the OTEL attributes, the agent is still created but the Owner column will show the raw ID.

  5. Inspect Claude's exporter logs — set OTEL_LOG_LEVEL=debug and look for OTLP export errors in Claude's stderr.

  6. Contact Capsule Security support if the issue persists.

Security Considerations

  • The bearer token is a long-lived JWT (365 days). Store it in a secret manager and distribute via MDM-protected channels.
  • Each token is scoped to a single tenant + environment. Compromising one token does not affect other environments.
  • To rotate the token, uninstall and reinstall the integration from the Capsule portal — this issues a new token; the old token continues to work until manually revoked.
  • The OTLP endpoint accepts only POST requests with a valid Authorization: Bearer <token> header. Unauthenticated requests are rejected with 401.

Support

For help with this integration:

  • Email: support@capsule.security
  • Include: Your tenant ID, the integration's environment external ID (visible in the portal), and any error messages from Claude's exporter logs

References

Previous page
Next page