> ## Documentation Index
> Fetch the complete documentation index at: https://docs.findtempo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Building on Canvas

> Wire authored templates into your AI agents over MCP. Auth, keys, the render lifecycle, and tracing.

Canvas exposes a public **MCP tool surface** that any AI agent can call — Claude, ChatGPT, Cursor, or anything else that speaks the Model Context Protocol. Templates authored in the Deal Brain web editor are immediately discoverable and renderable through these tools.

This page covers the concepts you need before reading the [MCP tool reference](/canvas/developers/mcp): how the surface fits together, how auth works, how keys resolve, what a render actually does, and how to find your renders in tracing.

## Architecture at a glance

```
┌──────────────────────────┐
│   AI Agent (Claude,      │
│   Cursor, ChatGPT, etc.) │
└──────────────────────────┘
            │  MCP
            ▼
┌──────────────────────────────────────────────────────────┐
│                Deal Brain Canvas MCP surface              │
│                                                            │
│   • list_templates    — discover templates                │
│   • generate_template — render against opportunity ctx    │
└──────────────────────────────────────────────────────────┘
            │
            ▼
┌──────────────────────────┐
│   Template store         │
│   (scoped to             │
│    System / Org / User)  │
└──────────────────────────┘
```

A template authored in the web UI is rendered the same way for every agent: scope-resolved, variables bound, status-gated, and traced in Langfuse with the template's key, status, and scope for audit.

## Authentication

| Surface | Auth                                                                                                                                                                                   |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **MCP** | OAuth-based MCP server authorization. Your agent obtains an MCP connection token through Deal Brain's auth flow; tokens are scoped to a single Deal Brain user and their organization. |

Templates resolve per-user, so the calling identity determines what's visible. A User-scoped template authored by Alice is not visible to a Bob-authenticated MCP session, even within the same organization.

## Template keys

Every template has a stable **key** — the string your agent uses to refer to it. Three conventions:

| Convention                          | Example                                             | Used for                                                                                             |
| ----------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| System keys                         | `daily-brief`, `meeting-debrief`, `draft-follow-up` | Deal Brain-shipped presets. Stable across releases.                                                  |
| Org/User templates with system keys | `daily-brief` (at Org or User scope)                | Overrides for a system preset.                                                                       |
| Custom keys                         | `user-templates/<slug>`, `drafts/<slug>`            | Templates authored by your team or customer. Prefix conventions help group them in `list_templates`. |

Keys are case-sensitive. Treat them as opaque identifiers in your code — Deal Brain may add new system keys over time, but existing ones won't change.

## The render contract

A call to `generate_template` does six things:

1. **Resolves the template** by key, applying User > Org > System precedence for the calling user.
2. **Verifies status** is `Active`. Draft templates return an error.
3. **Binds context** — opportunity ID, identity (user/org), and any additional variables you pass.
4. **Substitutes data variables** with their resolved values; preserves missing values as empty strings.
5. **Emits the rendered body** — markdown with `data` variables filled in and `instruction` variables flagged as model directives.
6. **Returns the system prompt + rendered body** in two text blocks, with cache hints for the model.

Steps 1–5 are deterministic — the same template + the same context + the same calling user always produces the same render. Step 6 hands off to an LLM, where determinism ends.

## Tracing

Every Canvas render emits a Langfuse trace with these metadata fields:

| Field                                            | Value                                                             |
| ------------------------------------------------ | ----------------------------------------------------------------- |
| `triggerType`                                    | `mcp` for agent calls, `cron` for scheduled internal jobs         |
| `triggerName`                                    | The tool name, e.g. `generate_template`                           |
| `workflowName`                                   | The bounded-workflow name, e.g. `generate-meeting-brief-pipeline` |
| `organizationId`                                 | The calling user's org                                            |
| `opportunityId`                                  | The bound opportunity, if any                                     |
| `templateKey`, `templateScope`, `templateStatus` | Set on render-time metadata                                       |

Use these for usage analytics, debugging, and audit.

## Next steps

<Card title="MCP tool contract" icon="robot" href="/canvas/developers/mcp">
  The full `generate_template` and `list_templates` reference — input schemas, output shapes, error modes, and integration patterns.
</Card>