# Setup skill for coding agents

This page is written for a coding agent (Claude Code, Cursor, Codex, VS Code or any other) that has been asked to set up Telltale in an application. A person pastes one prompt from **Connect your channels** in the Telltale dashboard; the prompt points here and gives you the site's publishable key and the Telltale server's address. It never contains a server key.

Work in small steps, propose each change before you make it, and stop to ask when something below does not match the application.

## 1. Find out what kind of application this is

Look at the repository before you change anything:

- **A website or web app people sign in to** (React, Next.js, Vue, Nuxt, WordPress, Shopify, Webflow, plain HTML): add the browser tag (step 2), then identify signed-in users from the server (step 3).
- **An MCP server**: wrap it with Telltale for MCP servers (step 4).
- **An HTTP API that agents call**: add the API middleware (step 4).

Many products have more than one of these. Do the web app first.

## 2. Add the browser tag

Read https://app.trytelltale.dev/docs/quickstart.md and the guide for the framework you found (https://app.trytelltale.dev/docs/nextjs.md, react.md, wordpress.md, shopify.md, webflow.md or gtm.md). Use the publishable key from the prompt (`ao_pk_...`). It is public and safe in page code.

Ask the person one question before you add it: **does the site show a cookie or consent banner?** If it does, hold collection until consent (`data-telltale-wait-for-consent` on the tag, or `waitForConsent: true`) and connect the banner as in https://app.trytelltale.dev/docs/consent.md. If it does not, the tag records on page load.

If the site sends a Content Security Policy, follow https://app.trytelltale.dev/docs/csp.md. Never add `unsafe-inline` or `unsafe-eval`.

## 3. Tell Telltale who is signed in, from your server

After sign-in, your backend calls `identify({sessionToken, userId, accountId})` with the server adapter (https://app.trytelltale.dev/docs/server.md). Use the application's own opaque IDs. Never send names, email addresses, passwords, cookies or anything a person typed.

The server key (`ao_sk_...`) belongs in the server's secret store or environment, never in page code and never in the repository. The person creates it in Settings › Channels. Ask them for it; do not invent one.

## 4. MCP servers and APIs

- MCP server: https://app.trytelltale.dev/docs/mcp.md. One wrapper; Telltale receives tool names, outcomes and timings, never arguments or results.
- API: https://app.trytelltale.dev/docs/api-channel.md. One middleware for Node http, Express, Next.js, Hono or Fastify.

Both use the server key from the environment and an `identify` hook that returns the account and user IDs your server already knows.

## 5. Check that it works

1. Run the application locally or on a preview deployment and open a page with the tag.
2. In the Telltale dashboard, **Connect your channels › Is it working?** ticks **First session received** and its heading turns to "It’s working" within a few seconds.
3. If nothing arrives, read https://app.trytelltale.dev/docs/troubleshooting.md: the usual causes are an address that is not on the site's allowed list, a wrong key, waiting for consent, or a CSP block.

## 6. Report back

Tell the person what you changed, file by file, what you tested, and what you could not test (for example consent withdrawal or a production-only CSP). Leave the merge to them.

## What never to do

- Never put the server key in browser code, a public repository or a log.
- Never collect typed content, credentials, cookies or request bodies for Telltale.
- Never treat a Telltale verdict as permission: protected actions still need your application's own authorization.

More: https://app.trytelltale.dev/llms.txt lists every page, and the docs MCP server at https://app.trytelltale.dev/mcp serves them on demand.