# Kết nối qua MCP

Kết nối Claude Desktop, Claude Code, Cursor, Codex hoặc một MCP client khác với các công cụ dự án cục bộ của Oleafly.

Oleafly có thể hoạt động như một máy chủ MCP (Model Context Protocol). Các MCP client như Claude Desktop, Claude Code, Cursor, Codex và Grok CLI có thể đọc, chỉnh sửa, tìm kiếm và biên dịch một dự án Oleafly. Bạn không cần khóa nhà cung cấp AI trong Oleafly vì client cung cấp mô hình.

Đây là lựa chọn khi bạn đã có thuê bao Claude (hoặc tương tự) và muốn ứng dụng trò chuyện đó điều khiển Oleafly, mà không cần dán khóa API vào [Settings](/docs/ai-setup/).

## Bật MCP

1. Mở **Settings → Integrations → Oleafly MCP**.
2. Bật công tắc **Enable MCP server**.

Máy chủ chỉ chạy khi tiến trình Oleafly còn mở. Nó chỉ lắng nghe trên `127.0.0.1`, không bao giờ trên mạng cục bộ của bạn. Đóng cửa sổ dự án không dừng máy chủ. Tắt MCP hoặc thoát Oleafly mới dừng được.

Oleafly ưu tiên cổng `5323` (`http://127.0.0.1:5323/mcp`). Nếu cổng này không khả dụng, máy chủ tự động gắn vào một cổng cục bộ còn trống khác và ghi nhớ nó cho lần khởi động tiếp theo. Settings hiển thị URL đang hoạt động. Nút khởi động lại của Settings dùng lại cổng hiện tại khi có thể hoặc chọn một cổng trống khác.

## Kết nối client của bạn

:::tip[Không cần chép token]
Lệnh `oleafly` có máy chủ MCP riêng giao tiếp qua đầu vào và đầu ra chuẩn. Nó tự tìm ứng dụng đang chạy và token của ứng dụng, nên bạn không phải chép URL hay token, và cũng không cần Node.js. `oleafly mcp config --client claude-desktop` in ra phần thiết lập; tên các client là `claude-code`, `claude-desktop`, `codex`, `cursor` và `gemini`. Xem [Công cụ dòng lệnh](/docs/cli/#connect-an-agent-over-mcp).
:::

Settings hiển thị các đoạn mã chép-dán sẵn cho các client phổ biến. Hãy chép URL đang hoạt động vì cổng được chọn có thể khác `5323`, sau đó thay `<token>` bằng bearer token từ Settings (Reveal / Copy).

### Claude Code

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

Thêm vào `claude_desktop_config.json` (cầu nối stdio qua `mcp-remote`, vì Desktop ưu tiên stdio):

```json
{
  "mcpServers": {
    "oleafly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "http://127.0.0.1:5323/mcp",
        "--header",
        "Authorization: Bearer <token>",
        "--transport",
        "http-only"
      ]
    }
  }
}
```

### Tiện ích mở rộng Claude Desktop

Mỗi bản phát hành đều có `oleafly.mcpb`, một tiện ích mở rộng cho Claude Desktop, nên bạn không cần tệp cấu hình hay token. Tải tệp từ [bản phát hành mới nhất](https://github.com/Oleafly/Oleafly/releases/latest) rồi mở bằng Claude Desktop để cài đặt.

Tiện ích này khởi chạy lệnh `oleafly` đi kèm ứng dụng và làm việc trên dự án đang mở trong Oleafly, vì vậy hãy để Oleafly chạy và bật máy chủ MCP. Nếu Claude Desktop không tìm thấy lệnh, hãy chọn nó trong phần cài đặt của tiện ích: `oleafly-cli` trong `Oleafly.app/Contents/MacOS` trên macOS, hoặc `oleafly-cli.exe` trong `%LOCALAPPDATA%\Oleafly` trên Windows.

MCP Registry liệt kê cùng tiện ích này với tên `io.github.Oleafly/oleafly`.

### Cursor / VS Code

Trong `.cursor/mcp.json` (hoặc cấu hình MCP của client bạn):

```json
{
  "mcpServers": {
    "oleafly": {
      "url": "http://127.0.0.1:5323/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

### Grok CLI

Trong `~/.grok/config.toml`:

```toml
[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }
```

### Codex CLI

Dùng đoạn mã **Codex CLI** trong cài đặt Oleafly, đoạn mã này cung cấp cầu nối stdio tới máy chủ đang chạy. Thêm mục vào cấu hình Codex của bạn và dùng URL cùng token đang hoạt động mà Oleafly hiển thị:

```toml title="~/.codex/config.toml"
[mcp_servers.oleafly]
command = "npx"
args = [
  "-y",
  "mcp-remote@latest",
  "http://127.0.0.1:5323/mcp",
  "--header",
  "Authorization: Bearer <token>",
  "--transport",
  "http-only"
]
```

Cầu nối yêu cầu Node.js và `npx`. Hãy khởi động lại hoặc kết nối lại client sau khi thay đổi cấu hình của nó.

Tệp `mcp.json` nằm cạnh dữ liệu Oleafly của bạn (hiển thị trong Settings) chứa cùng URL và token nếu bạn muốn viết script cho việc cài đặt. Nó chỉ được ghi khi máy chủ đang chạy (chế độ `0600` trên Unix) và bị xóa khi máy chủ dừng. Hãy đối xử với nó như bất kỳ bí mật cục bộ nào khác.

## Các công cụ có thể làm gì

Hầu hết các công cụ MCP dùng chung tên và schema với trợ lý trong ứng dụng. Các công cụ khám phá và định tuyến dự án do backend của ứng dụng desktop cung cấp.

Các công cụ nhắm vào dự án đang mở trong ứng dụng khi có dự án khả dụng. Khi một cửa sổ được kết nối, dùng `list_projects` và `open_project` để chọn dự án khác.

Sau khi cửa sổ cuối cùng đóng, backend vẫn giữ `read_file`, `list_files` và `search_project` khả dụng. Các thao tác ghi, thay thế, tạo và đổi tên gốc cũng vẫn khả dụng khi chính sách phê duyệt cho phép. Các công cụ này chỉ dùng dự án cuối cùng mà ứng dụng báo, và từ chối lời gọi nếu dự án đó không còn hợp lệ. Chúng không bao giờ đoán từ các dự án khác trong thư viện. Trạng thái, chọn dự án, xóa, biên dịch, nhật ký, kiểm tra PDF, đổi giao diện và các công cụ hình đòi hỏi một cửa sổ được kết nối.

### Định hướng

| Công cụ | Công dụng |
|---|---|
| `get_status` | Phiên bản Oleafly, dự án đang mở, công cụ tài liệu của nó, tài liệu chính, trạng thái biên dịch gần nhất, và lý do lần biên dịch gần nhất thất bại hoặc không chạy được |
| `list_projects` | Các dự án kèm ID, tên, engine, loại, tài liệu chính, dấu thời gian, màu, trạng thái xem trước và lịch sử xuất |
| `open_project` | Mở một dự án theo id để các công cụ khác nhắm vào nó |
| `list_files` | Cây tệp của dự án |
| `project_map` | Dàn ý, nhãn, trích dẫn, macro, đồ thị input, tham chiếu chưa giải quyết |
| `search_project` | Tìm văn bản trong dự án hiện tại |

### Đọc

| Công cụ | Công dụng |
|---|---|
| `read_file` | Đọc một tệp của dự án |
| `get_log` | Nhật ký biên dịch gần nhất |
| `get_pdf_text` | Văn bản trích xuất từ PDF đã biên dịch |
| `verify_pdf_pages` | Kiểm tra các trang PDF đã kết xuất để tìm lỗi bố cục, từ ảnh trang hoặc văn bản trang |

`get_pdf_text` và `verify_pdf_pages` đọc PDF cuối cùng mà Oleafly có. Khi lần biên dịch gần nhất thất bại hoặc không chạy được, kết quả của chúng nói rằng PDF đã cũ và lý do, vì nó đến từ một lần biên dịch trước hoặc là bản dở dang từ lần biên dịch thất bại. `get_log` cũng nói như vậy khi lần biên dịch gần nhất không chạy được, vì khi đó nhật ký của nó là từ một lần biên dịch trước.

### Chỉnh sửa

| Công cụ | Công dụng |
|---|---|
| `write_file` | Ghi hoặc ghi đè một tệp |
| `replace_in_file` | Tìm và thay thế trong một tệp |
| `create_file` | Tạo một tệp hoặc thư mục |
| `rename_file` | Đổi tên hoặc di chuyển một đường dẫn |
| `delete_file` | Xóa một tệp hoặc thư mục |
| `set_main_doc` | Đặt tài liệu làm điểm vào biên dịch |

### Biên dịch và hình

| Công cụ | Công dụng |
|---|---|
| `compile` | Biên dịch dự án thành PDF |
| `preview_figure` | Kết xuất riêng một hình và trả về ảnh PNG |
| `insert_figure` | Chèn hình vừa xem trước gần nhất vào tài liệu |
| `load_image` | Tải một ảnh từ dự án để làm việc với hình |

`compile` cho biết bản dựng có chạy được không, liệt kê các lỗi của nó, cho biết có PDF hay không, và kết thúc bằng phần cuối của nhật ký. Một bản dựng đã hoàn tất cũng báo các cảnh báo của nó. Khi bản dựng không chạy được, không hoàn tất, hoặc cần thứ gì đó nằm ngoài mã nguồn, chẳng hạn một bản cài TeX hoặc một phiên bản Typst chưa có, kết quả nêu lý do và gọi tên cách khắc phục mà Oleafly đang đề xuất cho bạn trong ứng dụng. Công cụ yêu cầu client báo cho bạn biết và để nguyên mã nguồn của bạn. Một lần biên dịch bạn đã dừng được đánh dấu là đã dừng, để client không coi đó là lỗi trong mã. Trợ lý riêng của Oleafly nhận cùng kết quả đó.

Hãy gọi `get_status` trước để biết dự án là LaTeX, Typst hay Markdown, rồi viết mã nguồn theo định dạng đó. `preview_figure` và `insert_figure` hoạt động trong các dự án LaTeX và Typst:

- Trong LaTeX, hình là mã TikZ được biên dịch trong một tài liệu standalone nhỏ, và `insert_figure` bọc nó trong môi trường `figure`.
- Trong Typst, hình là markup Typst, chẳng hạn một canvas CeTZ hoặc sơ đồ fletcher, được kết xuất bằng phiên bản Typst của dự án. `insert_figure` bọc nó trong `#figure`, đặt nhãn ngay sau nó và chuyển các dòng `#import` của nó lên trên.
- Trong dự án Markdown, cả hai công cụ đều trả về lỗi và không thay đổi gì.

`load_image` hoạt động trong mọi dự án.

### Ứng dụng

| Công cụ | Công dụng |
|---|---|
| `toggle_theme` | Chuyển đổi chế độ sáng / tối |

### Kỹ năng

| Công cụ | Công dụng |
|---|---|
| `list_skills` | Liệt kê các kỹ năng đã cài đặt kèm ID, tên, mô tả và trạng thái bật/tắt |
| `load_skill` | Tải toàn bộ hướng dẫn của một kỹ năng cùng danh sách tệp của nó |
| `read_skill_file` | Đọc một tài liệu tham chiếu hoặc script từ thư mục của một kỹ năng |

Các công cụ kỹ năng hoạt động ngay sau khi kết nối, mà không cần dự án nào mở và không cần cửa sổ Oleafly. Client thấy mọi kỹ năng hợp lệ, kể cả những kỹ năng đã tắt trong Settings: các công tắc quyết định kỹ năng nào mà chính trợ lý của Oleafly dùng, chứ không quyết định client được đọc gì. Các agent đọc kỹ năng từ thư mục thay vào đó có thể dùng **Share skills with other agents on this computer** trong **Settings → AI Assistant → Skills**. Xem [Kỹ năng](/docs/skills/).

### Notes

Các công cụ này có mặt khi **Notes** đang bật trong **Settings → Experimentation**, như [Bật Notes](/docs/notes/#turn-on-notes) mô tả. Chúng làm việc trên các ghi chú của bạn, không phải trên dự án đang mở, và cần một cửa sổ đã kết nối.

| Công cụ | Chức năng |
|---|---|
| `list_knowledge_notes` | Liệt kê các ghi chú của bạn, mới nhất trước, kèm ID, tiêu đề, thẻ gắn nhãn, dự án được liên kết và tóm tắt ngắn. Lọc theo thẻ gắn nhãn hoặc dự án |
| `search_notes` | Tìm kiếm các ghi chú của bạn và trả về ID, tiêu đề, thẻ gắn nhãn, liên kết và các đoạn trích khớp |
| `read_note_by_id` | Đọc một ghi chú dưới dạng Markdown kèm front matter của nó |
| `today_note` | Đọc ghi chú hằng ngày của hôm nay, hoặc tiêu đề mà nó sẽ có nếu chưa tồn tại |
| `list_note_tasks` | Liệt kê các tác vụ dạng hộp kiểm trong các ghi chú của bạn, ghi chú mới nhất trước. Lọc theo ghi chú và theo còn mở hay đã xong |
| `note_backlinks` | Liệt kê các ghi chú liên kết đến một ghi chú, kèm văn bản quanh mỗi liên kết |
| `append_to_note` | Thêm Markdown vào cuối một ghi chú hoặc vào cuối ghi chú hằng ngày của hôm nay |
| `edit_note_section` | Viết lại phần của một ghi chú nằm dưới một tiêu đề, hoặc thêm vào cuối phần đó |
| `create_note` | Tạo một ghi chú với tiêu đề, Markdown, thẻ gắn nhãn và một dự án được liên kết |

`append_to_note` và `edit_note_section` không ghi vào ghi chú. Các thay đổi của chúng hiển thị trong ghi chú dưới dạng đề xuất cho đến khi bạn chấp nhận chúng trong Oleafly. `create_note` chờ bạn phê duyệt trong Oleafly, và `append_to_note` cũng vậy khi nó phải tạo ghi chú hằng ngày của hôm nay trước. Dưới **Trust this connection**, việc tạo một ghi chú không hỏi. Một ghi chú được chia sẻ qua một máy chủ cộng tác có thể được đọc nhưng không thể thay đổi theo cách này. **Read-only** gỡ ba công cụ thay đổi ghi chú.

## Phê duyệt và an toàn

Nhiều MCP client hỏi trước khi gọi một công cụ. Oleafly cũng áp dụng chính sách được chọn trong **Settings → Integrations → Oleafly MCP**:

- **Confirm every change** là mặc định. Các thao tác ghi, đổi tên và xóa hiển thị một thẻ phê duyệt khi một cửa sổ ứng dụng được kết nối. Không có cửa sổ, các thao tác đó bị từ chối vì không có nơi nào hiển thị thẻ.
- **Auto-approve edits, confirm deletes** cho phép các thao tác ghi và đổi tên chạy trong backend. Xóa vẫn cần một cửa sổ được kết nối để xác nhận.
- **Trust this connection** cho phép các thao tác ghi và đổi tên trong backend chạy mà không cần nhắc từ Oleafly. Xóa vẫn đòi hỏi một cửa sổ được kết nối. Chỉ dùng chính sách này khi bạn tin tưởng client và các kiểm soát phê duyệt riêng của nó.

Hai công tắc nữa hỗ trợ cho việc này:

- **Read-only** (công tắc riêng) loại bỏ hoàn toàn các công cụ thay đổi khỏi `tools/list`, nhờ đó một ứng dụng bên ngoài có thể đọc và biên dịch nhưng không bao giờ chỉnh sửa tệp, bất kể chính sách ở trên.
- **Bearer token**: một giá trị ngẫu nhiên 256 bit được lưu trong bộ lưu trữ cục bộ mã hóa có xác thực dưới `~/.oleafly/`. Hãy tạo lại nó để vô hiệu hóa các client cũ. Các lần đọc cấu hình chung không bao giờ tiết lộ token. Chỉ các điều khiển kết nối của máy chủ đang chạy mới có thể hiển thị nó trong Settings.

Và hai điều bất biến mà bạn không cấu hình:

- **Localhost only**: địa chỉ gắn là `127.0.0.1`. Các yêu cầu mang header `Origin` của trình duyệt bị từ chối, và `Host` phải là loopback.
- **Project confinement**: các công cụ tệp của backend chấp nhận đường dẫn tương đối dự án và giới hạn đường dẫn chuẩn vào dự án mà ứng dụng báo. Một lời gọi công cụ không thể cung cấp ID dự án khác hoặc bắt backend chọn một dự án thư viện khác.

## Xem nó hoạt động

Khi một cửa sổ được kết nối, thẻ **MCP activity** ghi lại các lời gọi đến. Các lời gọi backend có thể tiếp tục sau khi cửa sổ cuối cùng đóng, nhưng sẽ không có bảng hoạt động hay thẻ phê duyệt cho đến khi một cửa sổ kết nối lại.

## Tại sao claude.ai trong trình duyệt không thể kết nối

Một dịch vụ trò chuyện trên đám mây không thể truy cập `127.0.0.1` trên máy của bạn. Hãy dùng **Claude Desktop** (hoặc Claude Code, Cursor, v.v.) thay thế. Đừng tạo đường hầm đưa cổng MCP ra internet công cộng: điều đó sẽ cho phép bất kỳ ai có URL chỉnh sửa và xóa các tệp dự án cục bộ của bạn.

## Xử lý sự cố

| Triệu chứng | Cách khắc phục |
|---|---|
| Một số công cụ không khả dụng | Xem trước hình và các công cụ chỉ có trên giao diện khác cần một cửa sổ Oleafly. Hãy mở ứng dụng và dự án, rồi thử lại `tools/list`. |
| Cổng khác `5323` | Cổng ưu tiên không khả dụng nên Oleafly đã chọn một cổng trống. Hãy chép URL đang hoạt động từ Settings. |
| HTTP 401 | Token không khớp (ví dụ sau khi Regenerate). Hãy chép token mới vào client. |
| HTTP 403 | Client đã gửi header `Origin` hoặc `Host` không phải loopback. Hãy dùng MCP client bản địa, không phải thẻ trình duyệt. |
| Lời gọi quá thời gian chờ | Mỗi lời gọi công cụ chờ tối đa **5 phút** (300 s) cho việc biên dịch hoặc cho bạn nhấn Approve. Hãy phê duyệt hoặc từ chối các thẻ đang chờ, hoặc thử lại. Một lần biên dịch có thể mất lâu hơn, tới một giờ với notebook Quarto hoặc Calepin. Nó vẫn tiếp tục chạy trong Oleafly sau khi lời gọi hết thời gian chờ, và các công cụ cần cửa sổ Oleafly sẽ chờ nó, nên hãy để nó hoàn tất trước khi thử lại. |
| `compile` trả về một lý do thay vì các lỗi | Bản dựng không chạy được, chẳng hạn vì chưa cài TeX. Hãy dùng cách khắc phục mà Oleafly đề xuất trong ứng dụng, như cài TinyTeX, rồi biên dịch lại. |
| Không thể kết nối | Oleafly phải đang chạy với MCP được bật. Máy chủ này dừng khi bạn thoát; để dùng công cụ dự án khi ứng dụng đã đóng, hãy kết nối client với `oleafly mcp`. |

## Thêm công cụ bên ngoài vào Oleafly

![Settings → AI Assistant → MCP. Thêm một máy chủ, duyệt registry, hoặc nhập cấu hình từ công cụ khác.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

Để cấp thêm công cụ cho trợ lý tích hợp sẵn, hãy mở **Settings → AI Assistant → MCP**.

- **Browse registry** để tìm một máy chủ và xem lại cách thiết lập của nó.
- **Import from other tools** để chọn các cấu hình máy chủ sẵn có. Hãy xem lại các mục đã chọn trước khi nhập.
- **Add server** để tự nhập một máy chủ, sau đó xác thực kết nối.

Các máy chủ đã kết nối cung cấp công cụ của chúng cho trợ lý. Bạn có thể xem trạng thái kết nối và bật hoặc tắt máy chủ từ cùng một trang. Thông tin đăng nhập và lệnh thuộc về từng cấu hình máy chủ; hãy xem lại chúng trước khi kết nối máy chủ mới.

alphaXiv cũng kết nối như một máy chủ MCP, nhưng bạn thiết lập nó trong **Settings → Integrations → alphaXiv** bằng khóa API thay vì ở đây. Sau khi kết nối, nó xuất hiện trong danh sách này với tên **alphaXiv**. [Kết nối nguồn nghiên cứu](/docs/integrations/research-sources/#alphaxiv) trình bày các bước.

## Tự cấu hình một máy chủ bên ngoài

![Add server → Form. Chọn Local command hoặc Remote URL, điền các trường kết nối, rồi dùng Add và xác thực.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

Trong **Settings → AI Assistant → MCP**, chọn **Add server**. Máy chủ cục bộ chạy một lệnh qua stdio; máy chủ từ xa kết nối tới một URL. Biểu mẫu JSON dùng định dạng máy chủ của Oleafly:

```json title="Cấu hình máy chủ cục bộ"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

Thay lệnh và đối số bằng những gì được ghi trong tài liệu của máy chủ bạn đã cài. Các giá trị biến môi trường nằm trong đối tượng `env`.

```json title="Cấu hình máy chủ từ xa"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

Thay URL và token mẫu bằng thông tin kết nối của dịch vụ. Dùng **Validate** để kiểm tra kết nối, rồi xem lại các công cụ mà máy chủ cung cấp. Bật hoặc tắt máy chủ từ hàng của nó. Dùng hành động sửa của nó để thay đổi cấu hình và hành động xóa để ngắt kết nối.

## Nhập cấu hình MCP sẵn có

Chọn **Import from other tools**, kiểm tra các cấu hình được phát hiện, và chọn máy chủ bạn muốn. Hãy xem lại đường dẫn tệp thực thi, biến môi trường, URL và thông tin đăng nhập trước khi nhập. Tính năng này nhập các thiết lập kết nối; nó không cài tệp thực thi của máy chủ giúp bạn.

## Thử kết nối

1. Mở một dự án luyện tập nhỏ trong Oleafly.
2. Kết nối client bên ngoài bằng đoạn mã đã chép từ ứng dụng.
3. Yêu cầu client gọi `get_status` và liệt kê các tệp của dự án.
4. Yêu cầu nó đọc tài liệu chính và gợi ý một thay đổi tiêu đề.
5. Xem lại hành động trong Oleafly trước khi phê duyệt một thao tác ghi.
6. Biên dịch và kiểm tra PDF.

Với một công cụ bên ngoài đã kết nối bên trong Oleafly, hãy bắt đầu bằng một yêu cầu chỉ đọc đơn giản mà máy chủ đó hỗ trợ và kiểm tra thẻ công cụ xuất hiện trong phần trò chuyện.
