# 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 Event | Description |
|  --- | --- |
| **user_prompt** | User prompts submitted to Claude |
| **tool_result** | Tool execution results, including MCP tool invocations |
| **api_request** | Model API requests with token usage, duration, and cost |
| **api_error** | Model API errors |
| **tool_decision** | Tool permission decisions (allow / deny / source) |
| **session_start** | Session 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:

| Variable | Value |
|  --- | --- |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | `1` |
| `OTEL_LOGS_EXPORTER` | `otlp` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/json` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | The `endpoint` from Step 1 (without the `/v1/logs` suffix if your client appends it; otherwise paste the full URL) |
| `OTEL_EXPORTER_OTLP_HEADERS` | `Authorization=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):


```bash
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:

| Platform | Recommended Mechanism |
|  --- | --- |
| **macOS** | Configuration 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 |
| **Windows** | Group Policy → User Configuration → Preferences → Windows Settings → Environment, or Intune Configuration Profile |


Refer to the [Jamf Pro](/guides/mdm-jamf), [Kandji](/guides/mdm-kandji), [Intune](/guides/mdm-intune), [SCCM](/guides/mdm-sccm), and [Tanium](/guides/mdm-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

| Resource | How It's Created |
|  --- | --- |
| **Agent** | One 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 entities** | One per path in `workspace.host_paths` |
| **Tool entities** | One per built-in tool used (Bash, Read, Edit, etc.) |
| **MCP Tool entities** | One per `<mcp_server_name>:<mcp_tool_name>` combination, tagged with protocol `MCP` |
| **Model entities** | One 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:

```bash
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

- [OpenTelemetry OTLP/HTTP Specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp)
- [OpenTelemetry Environment Variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/)
- [Claude Code OpenTelemetry Monitoring](https://docs.claude.com/en/docs/claude-code/monitoring-usage)