---
name: kensa-setup
description: Use when asked to install Kensa in an application repository, connect a coding agent to Kensa, or set up Kensa tracing. Configure project-scoped MCP and verify receipt of a real application trace. Do not use for investigating or fixing issues in an already connected application.
compatibility: Requires application repository access, network access to Kensa and package registries, and a coding client with HTTP MCP and OAuth support.
---

# Set up Kensa

Complete setup with a callable, authenticated MCP connection and a verified application trace. If blocked, report the missing prerequisite and the next action needed to resume.

Keep setup in the coding agent except for browser sign-in, consent, and credential entry. A GitHub connection is not required. Deploy only when the user requests deployment; never report an undeployed fix.

## 1. Inspect and choose the tracing path

Identify the language, package manager, startup entry point, existing tracer provider/exporters, and secret store. Use the repository's package manager and install tracing packages as runtime dependencies.

Prefer existing Langfuse or OpenTelemetry instrumentation. Use `kensa-sdk` (npm for TypeScript/Node, PyPI for Python) when a Kensa exporter is needed. The Python package imports as `kensa`; TypeScript uses `import { kensa } from "kensa-sdk"`.

Read the current SDK/API examples at the serving origin's `/docs` and the relevant framework documentation before changing instrumentation. Apply only the tracing path that fits the application.

## 2. Connect and authenticate MCP

Use the origin that served these instructions for `/api/mcp`, normally `https://kensa.sh`. In the examples below, replace the origin when using a local or preview server. Work in the application repository, not the Kensa repository. Merge the entry into the current client's project configuration; preserve existing MCP servers and settings. Reuse an existing project-scoped Kensa entry only after verifying its URL and connected project. If another Kensa entry shadows the project entry, explain the conflict rather than changing the user's personal configuration.

Configure the current client's native HTTP MCP support in the application repository:

- **Claude Code:** merge `{"mcpServers":{"kensa":{"type":"http","url":"https://kensa.sh/api/mcp"}}}` into the repo's `.mcp.json`, or run `claude mcp add --transport http kensa --scope project https://kensa.sh/api/mcp`. Use `/mcp` to authenticate.
- **Codex:** merge `[mcp_servers.kensa]` with `url = "https://kensa.sh/api/mcp"` into the repo's `.codex/config.toml`. Codex loads project configuration in trusted repositories. Run `codex mcp login kensa` to authenticate; `codex mcp add` writes user-level configuration, so do not use it here.
- **Cursor:** merge `{"mcpServers":{"kensa":{"url":"https://kensa.sh/api/mcp"}}}` into the repo's `.cursor/mcp.json`, then use Connect in MCP settings.
- **OpenCode:** check the installed version. For stable OpenCode, merge `{"mcp":{"kensa":{"type":"remote","url":"https://kensa.sh/api/mcp"}}}` into the repo's `opencode.json` (or existing `opencode.jsonc`). For OpenCode V2, merge `{"mcp":{"servers":{"kensa":{"type":"remote","url":"https://kensa.sh/api/mcp"}}}}` into the repo's `opencode.jsonc`. Run `opencode mcp auth kensa` to authenticate.

Follow installed-client help for version-specific configuration and reload behavior. Start authentication from the coding client, surface any sign-in URL to the user, and resume in the same agent session after they approve it in their browser. Do not automate browser sign-in. Use OAuth without a tracing key or Authorization header in the Kensa entry. Store no Kensa credentials in project files; each developer's OAuth credentials remain in their own client storage. Do not read or construct the client's OAuth token storage.

Tell the user: "In your browser, sign in or create a Kensa account. Select or create your project, approve access, then return to this agent." Access can be revoked at `/oauth/connections`. If the current session needs a reconnect or restart to expose MCP tools, request that action and resume afterward. Configuration alone does not prove that tools are callable.

Call `get_setup_status` without a trace ID. Confirm the returned project is the intended one before configuring export. If it is a different project, stop without calling other Kensa tools or configuring export. Remove only the MCP entry added during this setup, if any; do not reauthenticate the shared `kensa` connection or change existing entries. Report the mismatch and that this client needs a separate connection for the intended project. Use `connectUrl` for incomplete source setup. If `otlpEndpoint` is null, report the missing runtime configuration instead of guessing an endpoint.

### Credentials

For SDK/OTLP, reuse the project's `KENSA_API_KEY` in its secret store. If absent, ask the user to generate it under "Add your API key" on the Kensa setup page (`connectUrl`, or with `?source=sdk` or `?source=otlp` for the manual steps), tell them to store it as `KENSA_API_KEY` in the application's secret store, and resume once they have. Never rotate an existing key automatically: that breaks current exporters. For Langfuse, send the user to `connectUrl` with `?source=langfuse` to enter its credentials there.

MCP OAuth and ingestion credentials are separate. Never put credentials in chat, command output, committed files, MCP arguments/results, or browser URLs. Reference environment variables in code. If storage needs user action, name the secret and destination, then resume after it is stored.

## 3. Configure export and instrumentation

Preserve existing providers and exporters. Do not register a second global provider or redirect another backend's generic `OTEL_*` configuration to Kensa.

| Application state | Action |
| --- | --- |
| Existing Langfuse | Connect the source through `connectUrl` with `?source=langfuse`; retain its instrumentation and export lifecycle. |
| Existing generic OTLP exporter | Configure export to the returned `otlpEndpoint` with the project key using the exporter's documentation; preserve other destinations. |
| Existing Python provider with Kensa SDK | Call `kensa.init(api_key=os.environ.get("KENSA_API_KEY"))` after provider setup; pass `provider=` if it is not globally registered. |
| Existing TypeScript provider with Kensa SDK | Add `kensa.spanProcessor({ apiKey: process.env.KENSA_API_KEY })` to its `spanProcessors`. |
| No tracer provider | Use `kensa.init({ apiKey: process.env.KENSA_API_KEY })` in TypeScript or `kensa.init(api_key=os.environ.get("KENSA_API_KEY"))` in Python. |

The SDK defaults to `https://ingest.kensa.sh/v1/traces`. Set `KENSA_ENDPOINT` when the returned `otlpEndpoint` differs. Call `kensa.init()` after any code that sets up a provider; TypeScript applications with an existing provider must use `spanProcessor()` instead.

### Create spans on the real application path

`kensa.init()` configures export; it does not instrument agent or tool calls. If instrumentation is absent, enable the framework's OpenTelemetry integration or add spans around actual agent execution and relevant tool calls. Follow its conventions for inputs, outputs, errors, and parent-child relationships. A synthetic setup-only span does not verify application instrumentation.

### Flush before execution ends

For Kensa SDK export in short-lived processes and serverless handlers:

- TypeScript: `await kensa.flush()`.
- Python: `kensa.flush()`.

Flush after spans end and before the process exits or invocation completes, including error paths. For streaming responses, flush after the stream's work and spans finish, not when first returning the stream. Implement this in application lifecycle code, not just the verification script. Other exporters use their documented flush and shutdown lifecycle.

## 4. Identify deployments

Fix monitoring needs `service.version` set to the deployed commit SHA and `deployment.environment.name` set to the actual environment. Do not label local verification traffic as production.

When creating its own provider, `kensa.init()` detects commits on Vercel, Render, and Railway, and environments on Vercel and Railway. It does not infer deployments from CI or local runs. Set Render's environment explicitly.

With an existing provider, set both attributes on that provider's resource from per-deploy platform variables. `OTEL_RESOURCE_ATTRIBUTES` is suitable only for values fixed per environment. With `@vercel/otel`, pass `attributes: { "service.version": process.env.VERCEL_GIT_COMMIT_SHA }`: it sets the environment itself, but otherwise uses the deployment ID as the version.

## 5. Verify and report

Run relevant repository checks after edits. Fix failures introduced by setup before claiming success.

1. Run a representative, safe application request through real instrumentation yourself; never create fixture traces. If no spans are created, fix instrumentation before proceeding.
2. Capture its original trace ID without exposing trace content or credentials, then complete the exporter flush lifecycle. For Langfuse, use the original Langfuse trace ID.
3. Call `get_setup_status` with that ID. Allow bounded retries for redaction/import latency. If it remains absent, inspect exporter errors and source configuration; report the blocker rather than retrying indefinitely.
4. Confirm setup only when `traceReceived` is true for that request. An ingestion acknowledgement, unrelated traffic, or `lastTraceAt` is insufficient.

Report `productionMonitoringReady` separately: local setup may succeed while production monitoring is not ready. Fix observation also requires a reported deployed revision and subsequent production traffic.

Leave MCP configured for `list_issues`, `get_issue`, and `report_fix`. Finish with this concise report:

- **Project:** confirmed project name and ID.
- **Verification:** original trace ID and `traceReceived`, or the exact blocker.
- **Production monitoring:** `productionMonitoringReady` and any remaining deployment or credential step.
- **Changes:** files edited and checks run.