# Kết nối AI với project

Cấu hình MCP và API key để AI đọc hoặc chỉnh template trong project.

Bạn có thể để AI đọc cấu trúc mẫu, giải thích dữ liệu hoặc chỉnh thiết kế ngay trong project qua **MCP (Beta)**. Kết nối này đưa các công cụ của Tembuilder vào ứng dụng AI bạn đang dùng; quyền thao tác được quyết định bởi API key của project.

## 1. Chọn kết nối theo việc muốn làm

Tembuilder có hai kết nối MCP:

| Kết nối | Dùng để | Cần key |
| --- | --- | --- |
| Docs MCP · `/docs/mcp` | Tìm và đọc tài liệu công khai. | Không. |
| Project MCP · `/mcp` | Đọc hoặc chỉnh template và Assets trong project. | Có. |

Nếu chỉ muốn AI tra cứu hướng dẫn, thêm server tại `https://<api-host>/docs/mcp` vào ứng dụng AI, không cần API key. Dùng cùng API host hiển thị trong trang **MCP (Beta)** của project. Các bước dưới đây dành cho kết nối Project MCP.

<figure class="doc-sim data-assets-illustration workflow-illustration" aria-label="Docs MCP đọc hướng dẫn · Project MCP làm việc với mẫu">
<div class="sim-stage"><div class="ds-columns"><div class="sim-panel"><div class="ds-head"><strong>Docs MCP</strong><div class="wf-actions"></div></div><div class="wf-rows"><div class="sim-focus"><span>/docs/mcp</span><small>Tài liệu công khai</small></div><div class=""><span>API key</span><small>Không cần</small></div></div></div><div class="sim-panel"><div class="ds-head"><strong>Project MCP</strong><div class="wf-actions"></div></div><div class="wf-rows"><div class="sim-focus"><span>/mcp</span><small>Templates · Assets</small></div><div class=""><span>API key</span><small>Theo project</small></div></div></div></div></div>
<figcaption>Docs MCP đọc hướng dẫn · Project MCP làm việc với mẫu</figcaption>
</figure>

## 2. Tạo API key trong project

Trong project cần kết nối, mở **API Keys** và tạo key với quyền phù hợp:

- `mcp:read`: đọc template, tài nguyên và thông tin phục vụ chỉnh mẫu.
- Thêm `mcp:write`: cho phép tạo, sao chép và lưu thay đổi qua các công cụ ghi.

Key xác định project mà AI truy cập. Lưu key vào phần cấu hình kết nối của ứng dụng AI; không cần dán secret vào nội dung yêu cầu chỉnh mẫu.

<figure class="doc-sim data-assets-illustration workflow-illustration" aria-label="API Keys → mcp:read · thêm mcp:write khi cần chỉnh">
<div class="sim-stage"><div class="sim-panel"><div class="ds-head"><strong>API Keys · MCP</strong><div class="wf-actions"></div></div><div class="wf-rows"><div class=""><span>mcp:read</span><small>Đọc nội dung</small></div><div class="sim-focus"><span>mcp:write</span><small>Tạo và lưu thay đổi</small></div></div></div></div>
<figcaption>API Keys → mcp:read · thêm mcp:write khi cần chỉnh</figcaption>
</figure>

## 3. Thêm server vào ứng dụng AI

Mở mục MCP hoặc kết nối công cụ trong ứng dụng AI. Dùng endpoint trên trang **MCP (Beta)** của project và header `ApiKey`. Ví dụ cấu hình:

```json
{
  "mcpServers": {
    "tembuilder-project": {
      "url": "https://<api-host>/mcp",
      "headers": { "ApiKey": "<YOUR_API_KEY>" }
    }
  }
}
```

Đây là mẫu cấu hình remote HTTP; vị trí nhập và định dạng cụ thể phụ thuộc client. Endpoint nằm trên API origin, không phải URL của trang dashboard. Nếu client dùng header Authorization, định dạng được nhận là `Authorization: ApiKey ...`, không phải Bearer.

<figure class="doc-sim data-assets-illustration workflow-illustration" aria-label="Trang MCP → sao chép endpoint và cấu hình kết nối">
<div class="sim-stage"><div class="sim-panel"><div class="ds-head"><strong>MCP · Project</strong><div class="wf-actions"></div></div><div class="ds-code sim-focus"><code>https://&lt;api-host&gt;/mcp</code><code>ApiKey: &lt;YOUR_API_KEY&gt;</code></div></div></div>
<figcaption>Trang MCP → sao chép endpoint và cấu hình kết nối</figcaption>
</figure>

## 4. Bắt đầu bằng việc đọc một mẫu

Sau khi kết nối, thử yêu cầu:

> Đọc capabilities và liệt kê template trong project. Với mẫu tôi chọn, giải thích cấu trúc và Parameters, chưa thay đổi nội dung.

Khi AI đã tìm đúng mẫu, hãy mô tả thay đổi bạn muốn và yêu cầu AI kiểm tra preview trước khi lưu. Sau đó mở lại mẫu trong editor để kiểm tra nội dung và dữ liệu.

Project MCP hỗ trợ tạo, chỉnh mẫu và visual preview. Để dùng thay đổi cho bản PDF chính thức, [lưu và publish trong app](/docs/vi/publishing/save-publish/), rồi [chạy render](/docs/vi/renders/preview-render/). MCP không có công cụ publish hay tạo job PDF lưu trữ.

<figure class="doc-sim data-assets-illustration workflow-illustration" aria-label="workspace_capabilities → template_list → template_context">
<div class="sim-stage"><div class="sim-panel"><div class="ds-head"><strong>MCP · tools</strong><div class="wf-actions"></div></div><div class="wf-tools"><div class="wf-tool"><small>01</small><code>workspace_capabilities</code><span>Khả năng của kết nối</span></div><div class="wf-tool"><small>02</small><code>template_list</code><span>Tìm mẫu trong project</span></div><div class="wf-tool"><small>03</small><code>template_context</code><span>Revision và cấu trúc mẫu</span></div><div class="wf-tool sim-focus"><small>04</small><code>template_read</code><span>Source hoặc phần schema cần đọc</span></div></div></div></div>
<figcaption>workspace_capabilities → template_list → template_context</figcaption>
</figure>