# MCP (AI agents)

This server connects AI assistants (Claude Desktop/web, Claude Code, Cursor, VS Code, Windsurf, n8n/Make
MCP client nodes, agent frameworks) to a project's templates: the same tool names across clients, a
per-project URL, auth by Bearer or `?api_token=`, and settings on the project's MCP page.

## Run it

| Mode | Command | Auth |
|---|---|---|
| Streamable HTTP (hosted) | `TRICID_BASE_URL=http://localhost:4000 pnpm --filter @render/mcp dev:http` (or `build` then `start:http` for the bundled server) → `http://127.0.0.1:4100/mcp` | each client sends the project API token as `Authorization: Bearer <token>` **or** `?api_token=<token>` |
| stdio (local assistant) | `TRICID_API_TOKEN=<token> TRICID_BASE_URL=http://localhost:4000 pnpm --filter @render/mcp start` | the token in the environment |
| Bundled | `pnpm --filter @render/mcp build`, then `node apps/mcp/dist/cli.js [--http --port 4100 --host 0.0.0.0]` | as above |

**URLs:**

| URL | Behaviour |
|---|---|
| `POST /mcp` | The token decides the project |
| `POST /mcp/{project_id}` | Per-project URL. A token from another project gets **403** |

The server is stateless: no sessions, so `GET` and `DELETE` return 405. Health check: `GET /healthz`.
Host-header protection is on for loopback binds; set `TRICID_MCP_ALLOWED_HOSTS` for public binds and
put TLS in front. `--no-query-token` disables `?api_token=`. Tokens are never logged.

Client set-up (Claude Code):

```bash
claude mcp add --transport http tricid http://localhost:4100/mcp/<project_id> --header "Authorization: Bearer <token>"
```

In JSON: `{"mcpServers":{"tricid":{"type":"http","url":"http://localhost:4100/mcp/<project_id>","headers":{"Authorization":"Bearer <token>"}}}}`.
For stdio: `{"command":"node","args":[".../apps/mcp/dist/cli.js"],"env":{"TRICID_API_TOKEN":"<token>","TRICID_BASE_URL":"http://localhost:4000"}}`.

## Settings: the project MCP page (Studio) → `GET /api/rest/mcp/config`

The server reads the project's settings from the API. Over HTTP the settings are cached for 30 s per token.
Over stdio they are re-read every 60 s, and tool switches reach the client as
`notifications/tools/list_changed`, so a reinstall is usually unnecessary.

| MCP page setting | Effect here |
|---|---|
| **Enable MCP server** | Off: HTTP returns 403 and stdio exposes no tools |
| **Templates**: All / Custom selection / By tag | Only the templates the API lists for the scope are visible or usable |
| **Usage instructions** (≤ 400 chars) | Appended to the server `instructions` the model reads |
| **MCP features** | Each tool is registered only when its switch is on (table below) |

`GET /api/rest/me` supplies `billing_mode`. With `off` (the owner default), finals need no balance. Credits
are still computed and reported.

**Fallback.** On an API without these endpoints, environment variables stand in:

| Variable | Effect |
|---|---|
| `TRICID_MCP_TEMPLATE_TAG` / `…_TEMPLATES` | Template scope |
| `…_INSTRUCTIONS` | Usage instructions |
| `…_ALLOWED_KINDS` | Allowed creative types |
| `…_DOCS=0` | Hides `get_docs` |
| `…_BILLING=off\|credits` | Billing mode |

**Operator caps** always apply on top of the project settings:
- `TRICID_MCP_ALLOWED_KINDS` narrows the creative types.
- `TRICID_MCP_MAX_CREDITS` caps the credits of a single call.
- `TRICID_MCP_ALLOW_LOCAL_FILES=1` (stdio only) lets `upload_media` read local files.

## Tools

| Tool | Feature switch | What it does |
|---|---|---|
| `list_templates` | List Templates (required) | In-scope templates, 20 per page (`next_cursor`): uuid, title, tags, size, dynamic layers and, from **Instruct AI**, `description` and `preferred_type`. Filters: `title_filter`, `tag`, `collection_id`, `order_by` |
| `show_template` | List Templates (required) | One template: Instruct AI description and preferred type; every dynamic layer with its **description**, all accepted properties (with `required`/`max_length` where the template sets them), an `example_layers` payload and prices |
| `create_image` | Create Images | `template_uuid`, `layers`, `mode`, `max_credits?`, `modifications`, `webhook_success`, `passthrough`, `wait_seconds`, `return_image` (attaches the picture for the model to look at) |
| `create_pdf` | Create PDFs | `pages[]` of `{template_uuid, layers}` (multi-page, several templates), `modifications` (filename, image_quality, dpi) |
| `create_video` | Create Videos | `clips[]` of `{template_uuid, layers, audio…}`; text and image may be arrays; `expected_duration_seconds` for the estimate |
| `get_creative` | on when any create tool is on | Status, URL and credits by `id` (`type` optional; all kinds are tried); optional `wait_seconds`. Long-polls on the server |
| `get_docs` | Search Documentation | Searches our docs: REST/URL API, SDK, webhooks, n8n/Make/Zapier, cURL/PHP/Python/Ruby samples |
| `estimate_credits` | (extra, with any create tool) | Cost of a final without rendering. Accepts `modifications` (output size, dpi, color_mode) |
| `upload_media` | (extra, with any create tool) | Base64 (or a local `file_path` on stdio) → URL for picture layers |

Resource: `tricid://guide` is a compact model-oriented guide, also searchable through `get_docs`.

### Cost and safety rules

- `mode` has no default. `"preview"` sends `output_mode: "preview"` and is free and watermarked.
- If the reply does not confirm a preview, the job is **deleted immediately** and the call fails, so a
  preview can never turn into a paid final by accident.
- Every result has `credits_estimate` and `credits_charged` (the server's `credits` field).
- Prices:

  | Kind | Price |
  |---|---|
  | Image | By output longest side: 1 / 8 / 16 / 32 |
  | PDF page | 2 / 4 / 8 / 16, ×2 when rasterised; minimum 2 |
  | Video | 10 per started 10 s |

- With billing enforced (`billing_mode: credits`, or unknown), a final needs `max_credits` ≥ the estimate.
  With billing off, `max_credits` is optional but still honoured.
- Unknown layer names or properties are rejected **before** rendering, with "did you mean" hints. A template
  whose Instruct AI preferred type differs from the requested kind produces a warning.
- Most clients time out at about 60 s. `wait_seconds` defaults to 30; after that, use `get_creative`.
