# @kody/canva-mcp — agent notes

Human setup and intent live in [`README.md`](./README.md). This file is for
agents: imports, smoke checks, snippets, and edge cases. Never paste tokens.
Do not disable live webhooks or jobs.

## Auth

| Lane | Credential | Notes |
| --- | --- | --- |
| Preferred | MCP server `canva` | `kody.mcpServerAdd` → authorize `authUrl`. Helpers use `kody.mcp["canva"]`. |
| Fallback | `@kody/canva` OAuth | BYO Canva Connect OAuth. See https://kody.codes/@kody/canva |

Do not register a Canva OAuth app for the one-click MCP path. After fork,
connect **the caller's** Canva workspace — do not treat live `@kody/canva-mcp`
as yours. MCP *server* name stays `canva`; `-mcp` is only the Kody package id.

## Import paths

| Export | Import |
| --- | --- |
| package overview / MCP setup | `kody:@kody/canva-mcp` |
| smoke-test | `kody:@kody/canva-mcp/smoke-test` |
| list-designs | `kody:@kody/canva-mcp/list-designs` |

Prefer static `kody:@kody/canva-mcp/...` imports from `execute`. Do not lead
with `packages.invoke`.

## Smoke test (read-only)

```js
import smokeTest from 'kody:@kody/canva-mcp/smoke-test'

export default async function main() {
	return await smokeTest()
	// MCP connected => { ok: true, live: true, via: 'mcp', ... }
	// otherwise => { ok: true, live: false, setup: { mcp, oauthApiFallback } }
}
```

## Common snippets

List designs:

```js
import listDesigns from 'kody:@kody/canva-mcp/list-designs'

export default async function main() {
	return await listDesigns({
		query: 'quarterly',
		limit: 10,
	})
}
```

Add MCP server (setup, not a package export):

```js
import { kody } from 'kody:runtime'

export default async function main() {
	return await kody.mcpServerAdd({
		name: 'canva',
		url: 'https://mcp.canva.com/mcp',
	})
	// open returned authUrl, then retry smoke-test / list-designs
}
```

## Edge cases / fork notes

- This package is MCP-only; full Connect API surface lives in `@kody/canva`.
- List helpers only return designs the authorizing user can already see.
- Helpers try several MCP tool name variants; missing tools surface as setup
  errors, not silent empty lists.
- Never paste Canva OAuth tokens or client secrets into chat or logs.