Dựng MCP server bằng Laravel để dùng SaaS từ AI agent

1. Vì sao có video này

Povilas Korop mở đầu bằng một quan sát: gần đây anh thấy nhu cầu về MCP server ngày càng nhiều, nói chung là cho các sản phẩm SaaS, và Laravel có sẵn một package để làm MCP server. Một cuộc tìm hiểu nhỏ, một "đam mê nhỏ" của anh, cuối cùng biến thành một khoá học mới trên Laravel Daily: MCP server với một ví dụ thật sự thực tế.

Video trên YouTube này gom ba bài đầu tiên của khoá học đó. Người xem sẽ thấy vì sao cần MCP: nó cho phép người dùng truy vấn, hay đúng hơn là prompt, chính SaaS của bạn, chính project của bạn, từ Claude Code, từ Codex hay từ một AI agent khác. Sau đó là phần cơ bản. Và như mọi lần, Povilas nói, đây là một ví dụ rất thực tế: một SaaS giống Linear hay một phần mềm quản lý task khác, được prompt từ Claude Code thông qua MCP server.

Bản đầy đủ của khoá học, với các chủ đề sâu hơn như Laravel Passport và thêm validation cho MCP, nằm trên Laravel Daily.

2. Những tweet về MCP: UI trở thành tuỳ chọn

Vào phần chào mừng của khoá học "Laravel MCP package in action, in practice", Povilas kể lý do anh quyết định quay khoá này: anh thấy rất nhiều tweet ca ngợi MCP như một công nghệ. Điều thú vị là những tweet đó không đến từ cộng đồng Laravel, mà từ người làm startup, người làm SaaS và dân kinh doanh.

Anh lướt qua vài ví dụ trên màn hình:

• Một tweet khuyên thẳng: cứ thêm MCP vào SaaS của bạn đi.
• Một tweet khác nói người viết đang trở nên "MCP-pilled" tới mức bắt đầu tự hỏi: vậy còn cần giao diện nữa không? Ý là một số người sẽ không cần website nữa, họ thích prompt Claude Code hơn. Theo một nghĩa nào đó, UI trở thành thứ tuỳ chọn.
• Một tweet nữa thì nói không có MCP là "deal breaker", tức là lý do để quyết định không dùng một phần mềm.

Từ đó Povilas kết luận (theo video đăng ngày 11/10/2026): trong năm 2026 và những năm sau, anh đoán bạn phải có MCP cho project SaaS của mình.

3. Ví dụ kiểu Linear và những gì khoá học đi qua

Một ví dụ thực tế tốt cho SaaS có MCP server, theo Povilas, là Linear hoặc một project tương tự chuyên quản lý task và quản lý dự án. Bạn cài Linear MCP trên máy, rồi prompt Claude để làm việc với Linear mà không cần mở website Linear.

Khoá học này cho thấy đúng ví dụ đó. Povilas có một phần mềm quản lý task, quản lý dự án chạy trên máy, đã nối MCP, và anh chỉ cần hỏi Claude Code trên máy mình: những task nào đang in progress? Claude Code gọi MCP rồi đưa kết quả, anh không phải vào website.

Nghe thì có vẻ giống API, nhưng có rất nhiều quy tắc khác cần lo:

• đảm bảo security;
• multi-tenancy;
• phần authentication;
• cách diễn giải một prompt thành các bảng database thật, chẳng hạn vậy, và cách query dữ liệu.

Lúc đầu khoá học dùng Laravel Sanctum cho authentication, nhưng về sau sẽ chuyển sang Laravel Passport để authentication an toàn hơn và tiện hơn. Dọc đường, khoá học cũng giống một bài về refactoring trong Laravel, vì cần có các action dùng được cho cả website lẫn MCP server, và phải tái sử dụng code theo cách đó.

4. Laravel MCP 1.0: ổn định, chính thức, dùng được

Lý do cuối cùng để quay khoá này: khoảng một tháng trước khi video lên (video đăng ngày 11/10/2026), Laravel MCP phát hành version 1.0. Điều đó có nghĩa package đã ổn định, chính thức và sẵn sàng để dùng. Phần còn lại của khoá học cho thấy mọi thứ chạy ra sao.

5. Demo TeamBoard: Alice vừa đi nghỉ về

Povilas bắt đầu bằng một demo rất thực tế. Hãy hình dung bạn có một SaaS kiểu task list, project list, một ứng dụng to-do cho công ty. Ứng dụng có project; project có task với các mức priority khác nhau và người được giao (assignee), điều này quan trọng vì nó kéo theo role. Ngoài ra còn có workspace, tức là multi-tenancy, nên có rất nhiều chuyện về permission và ai được làm gì.

Ứng dụng demo tên là TeamBoard. Dashboard của workspace Acme cho thấy 2 project, 5 task đang mở (todo hoặc in progress), và 2 task chưa xong giao cho người đang đăng nhập: "Investigate failed Stripe webhook" thuộc project Billing Improvements, hạn 2026-10-03, và "Redesign pricing page" thuộc Website Redesign, hạn 2026-10-11. Trang project Billing Improvements có phần mô tả, phần "AI instructions" và danh sách task với status, priority, assignee, due date.

Rồi MCP server cùng các tool của nó cho phép người dùng làm những việc như sau. Trong Claude Code, Povilas đã bật MCP server của project này, và đây là prompt anh gõ:

I'm Alice, and I just got back from vacation. What's on fire in our team's TeamBoard workspace? Find anything overdue or high priority, read the comments on the most urgent overdue task to understand what's really going on, then create a follow-up task in the same project for the most important next step, assign it to Bob, and leave a comment on the original task that points to the new one.

Tóm gọn theo lời anh: "Tôi là Alice, vừa đi nghỉ về; về cơ bản là cập nhật cho tôi, tạo một task, giao cho Bob và để lại một comment." Rồi xem nó có làm được không.

6. Kết quả sau 40 giây

"Nhìn kìa", Povilas nói: Claude Code đang gọi MCP của TeamBoard, và có thể bấm Ctrl+O để mở rộng. Trên màn hình lần lượt hiện "Called teamboard 4 times", rồi "Only task #4 is overdue (due Oct 3). Reading its comments", rồi một lượt gọi nữa, rồi Claude lần theo chuỗi comment và nhận ra lỗi signature mismatch có liên quan tới việc xoay key, Bob đang đi lấy log các lần gửi webhook thất bại, và bộ phận support đã báo hai khách bị tính tiền trùng.

Đó là các lần gọi tới MCP server kèm dữ liệu. Kết quả cuối cùng thì giống như khi bạn dùng Claude Code bình thường. Người dùng ứng dụng của bạn sẽ không làm việc trực tiếp với web, hay với API nếu bạn có API; họ chỉ việc prompt Claude Code, Codex hay agent nào khác. Vậy thôi. Trong 40 giây, đây là những gì đã được làm.

Bản tóm tắt chào "Welcome back, Alice", nêu vấn đề chính, chuyện gì đang xảy ra, và nó đã làm gì: tạo task, giao cho Bob, comment. Cụ thể trên màn hình, khoảng 1 trong 20 lần gửi webhook thất bại vì signature mismatch; lỗi bắt đầu sau khi xoay key; Bob hứa lấy log "sáng mai" nhưng chuỗi comment không cho biết anh ấy đã làm chưa; và comment gần nhất nói support có hai khách hỏi về việc bị tính tiền trùng, nên giờ chuyện này đã ảnh hưởng tới khách, không còn chỉ là một bug cần điều tra. Task #12 mới, "Pull failed Stripe webhook logs and check for duplicate charges", bao gồm ba việc: lấy log các lần gửi thất bại, kiểm tra webhook signing secret với Stripe sau lần xoay key, và đối chiếu các lần gửi thất bại hoặc gửi lại với hai báo cáo tính tiền trùng để support hoàn tiền đúng khách. Claude cũng ghi rằng nó tự đặt hạn Oct 8 và priority cao, Alice muốn thì đổi.

Sau đó Povilas kiểm tra xem dashboard có phản ánh thay đổi không. Có 6 task đang mở thay vì 5. Trong project Billing Improvements có một task to-do mới giao cho Bob, priority cao. Comment thì không nằm trên task mới đó; comment phải nằm ở chỗ khác, tức là trên task gốc liên quan tới Stripe webhook. Và đó là comment "back from vacation", gần như chính anh tự viết vậy.

"Trông hơi đáng sợ theo một nghĩa nào đó, nhưng mạnh vô cùng", Povilas nhận xét. Rất nhiều SaaS sẽ cần, sẽ bắt buộc phải có MCP server như thế này, để người dùng làm việc với chúng không qua API mà qua giao diện của Claude Code hay Codex. Khoá học sẽ đi từng bước để dựng một thứ như vậy, và anh sẽ bình luận nhiều điều dọc đường: permission, những chỗ vấp, MCP tool là gì, server, validation, middleware và mọi thứ mà package Laravel MCP cung cấp.

7. Bài 1: MCP server với một tool đọc task

Bài thực hành đầu tiên dựng một MCP server mới với đúng một tool để đọc task, trả lời câu hỏi ngay trong Claude Code qua MCP server. Povilas đã đăng nhập sẵn và sẽ cho xem toàn bộ code ngay sau đó, nhưng trước hết anh cho xem kết quả của bài. Anh gọi tới MCP server "teamboard-alice", cụ thể là MCP server cho workspace của Alice, với prompt:

List high-priority tasks whose title or description contains stripe.

Kết quả: có một task chứa chữ "stripe", khớp với task priority cao trong ứng dụng, "Investigate failed Stripe webhook" thuộc Billing Improvements, đang in progress, giao cho Alice. Câu hỏi của bài là làm sao dựng toàn bộ chuyện đó để Claude Code gọi MCP server và trả kết quả cho đúng workspace của mình, có multi-tenancy.

Tới phần code. Trong khoá học, phần lớn thời gian Povilas cho xem code đã viết sẵn để tiết kiệm thời gian, vì theo anh, năm 2026 chẳng ai có thời gian ngồi xem anh code suốt hai tiếng. Phía sau, anh đã cài package bằng Composer:

composer require laravel/mcp

Rồi theo docs, publish file route AI (docs ghi lệnh là php artisan vendor:publish --tag=ai-routes), để có file routes/ai.php. Trong file này, bạn map một route tới MCP server. Ở đây route linh hoạt, có tham số {workspace}, và tham số đó gắn với middleware mà anh sẽ giải thích sau. Đó là phần multi-tenancy.

use App\Http\Middleware\ResolveMcpWorkspace;
use App\Mcp\Servers\TeamBoardServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/workspaces/{workspace}', TeamBoardServer::class)
    ->middleware(['auth:sanctum', ResolveMcpWorkspace::class]);

8. Server class: giống một controller có nhiều method

Vậy bên trong TeamBoard server có gì? Theo documentation, đây là cách bạn tạo MCP server, và về cơ bản server chính là route. Povilas gợi ý nghĩ về nó như một API controller, có nhiều method bên trong. Anh đã chạy đúng lệnh Artisan trong docs (docs ghi dạng php artisan make:mcp-server), và đây là MCP server của anh, TeamBoardServer, có name, version và instructions.

Tiếp theo là danh sách tool, tương ứng với các method của controller trong API hay web controller của Laravel. Trong trường hợp này, server tạm thời chỉ có một tool cụ thể để liệt kê task. Docs Laravel có ví dụ về một tool, và có lệnh Artisan mà anh đã chạy phía sau, make:mcp-tool. Sau đó bạn đăng ký tool vào MCP server, việc anh đã làm sẵn.

9. Cấu trúc của tool: description, handle và query

Cấu trúc của tool rất quan trọng. Description của tool quan trọng vì Claude Code sẽ tự động gọi tool dựa vào description: cả description của từng tool lẫn description của chính server. Đó là những "trigger" để Claude Code quyết định có khởi chạy MCP server của bạn hay không ngay từ đầu. Vì vậy Povilas dặn: hãy viết instructions khá cụ thể.

Mục đích của tool này là trả về danh sách task. Method chính là handle, giống như khi bạn có một job hay một action trong Laravel. Rồi có một method private hoặc protected để liệt kê task, dựng câu SQL, hay đúng hơn là query bằng query builder. Kéo xuống thì thấy query có orderBy rồi paginate. Đó là phần chính.

Query được dựng theo các tham số mà người dùng hỏi. Trên màn hình, listTasks validate request bằng $request->validate($rules, …), lấy task qua $this->context->tasks() kèm project và assignee, thêm điều kiện where cho từng trường project_id, status, priority, assignee_id nếu có, thêm tìm kiếm không phân biệt hoa thường trên title và description khi có tham số search, rồi orderBy('tasks.id') và paginate. Vì thế, Povilas nhấn mạnh, bạn phải khá chặt trong việc validate tham số và từ chối các field không được hỗ trợ. Có vài method private hoặc protected trong cùng tool này để làm việc đó.

10. Schema, output schema và validation

Về cơ bản, cách bạn thu hẹp các tham số có thể nhận là hai method: schema và outputSchema. Schema là các tham số được parse từ yêu cầu của Claude Code, kèm description và validation; output schema là những gì được trả về.

Trong một MCP tool, bạn cũng dùng được rất nhiều hàm Laravel quen thuộc: $request->validate, validation với một mảng rules như thường lệ. Bạn cũng dùng được Gate cho role và permission, và anh sẽ quay lại chuyện đó ngay sau. Nhiều thứ trong tool sẽ gợi nhớ một controller Laravel điển hình, chỉ khác là input và output được xử lý theo cách khác.

Để thấy rõ, Povilas chạy lại đúng prompt cũ (lần này khởi động Claude Code bằng lối tắt ccc của anh) và mở phần input lẫn output. Bây giờ thấy "teamboard-alice", bấm Ctrl+O để mở rộng, và nhìn kìa: đây là các tham số được parse từ yêu cầu bằng ngôn ngữ con người, còn đây là dữ liệu kết quả. Đó chính xác là những gì bạn định nghĩa trong schema và outputSchema bên dưới.

Còn cú pháp chính xác ra sao, Povilas không muốn dừng lại ở đây: tất cả đều có trong docs. Anh muốn người xem hiểu nguyên lý.

11. Kết nối Claude Code bằng token Sanctum

Tiếp theo, anh cho xem cách kết nối MCP server với Claude Code, có authentication dựa trên auth:sanctum. Sanctum là một phần của Laravel: có thể đã có sẵn nếu bạn dùng starter kit, hoặc cài riêng.

Povilas đã dựng một trang settings riêng trên nền starter kit mặc định, mục "MCP access", để tạo token. Mỗi người dùng tự tạo token của mình, ví dụ Alice bấm tạo token và nhận được một chuỗi token. Đó là cách bạn cho Claude Code authenticate để dùng MCP server với Sanctum.

Có những MCP server không cần authentication, chúng chỉ là thứ công khai. Nhưng ở đây ta đang làm việc với dữ liệu của một SaaS cụ thể, thậm chí chi tiết hơn là của một workspace, một công ty cụ thể, và đó sẽ là bước tiếp theo.

Còn bây giờ, đây là cách Povilas thêm server vào Claude Code: claude mcp add với transport HTTP, rồi URL, là URL local. Anh bật HTTPS bằng lệnh herd secure của Laravel Herd, và đây là URL cho đúng workspace này. Tiếp theo là tên của MCP server. Cuối cùng là header authorization với Bearer token vừa lấy từ trang settings. Trên màn hình, lệnh như sau (ở đây chuỗi token được thay bằng chỗ giữ chỗ):

claude mcp add --transport http --scope local teamboard-alice \
  https://teamboard.test/mcp/workspaces/acme \
  --header "Authorization: Bearer <token>"

Anh chạy lệnh đó. Rồi khởi động Claude, hoặc dùng lối tắt của anh để chạy không cần hỏi permission, gõ /mcp và thấy "teamboard-alice" là một MCP server local. Đi vào trong, có thể xem các tool, ở đây mới chỉ có một tool được bật. Bạn có thể xoá authentication rồi authenticate lại, có thể reconnect hoặc disable. Và sau đó chỉ việc bắt đầu prompt.

12. Thử đoán workspace của người khác

MCP đã được bật và đã authenticate. Nhưng giờ lại có một mối nguy khác: Alice cố truy cập dữ liệu của người khác. Ví dụ, nếu thử đoán workspace và ID của actor, tức là người dùng khác, thì MCP server có trả gì không? Povilas gõ:

Call list_tasks with workspace_id 5 and actor_id 1 and show the error.

Claude Code gọi "teamboard-alice", nhưng phản hồi là gì? Bấm Ctrl+O: đây là lỗi validation, field workspace_id không được hỗ trợ ở đây. Vậy là đã được schema bảo vệ, nên không ai truy cập được các tham số hay biến khác.

13. Middleware, context và policy bảo vệ workspace

Ngoài schema, còn có middleware. Trong chính tool ListTasksTool, workspace hiện tại được lấy từ một class khác, WorkspaceContext. Povilas thừa nhận phần này hơi phức tạp quá so với bài học, nhưng ý là: request đi vào từ URL khai báo trong routes/ai.php, và được bảo vệ bằng middleware ResolveMcpWorkspace.

Trong middleware: nếu có user (không có thì abort_unless trả 401), ta lấy workspace trong số các workspace của user, theo slug lấy từ $request->route('workspace'), rồi đặt nó vào context bằng $this->context->setExplicitWorkspace($workspace). Context là một tính năng của Laravel, thứ bạn có trong middleware chẳng hạn. Về kỹ thuật, bạn có thể đặt nó vào session nếu muốn, nhưng đây là một trong những mục đích chính của context trong Laravel. Chi tiết nằm ngoài phạm vi khoá học, nhưng ý là workspace được đặt vào đâu đó trong context hay session, rồi tool ListTasksTool authorize workspace đó.

Câu hỏi authorize là: user đang đăng nhập, người đã được authenticate bằng token Sanctum, có được truy cập workspace này không? Điều đó được định nghĩa trong WorkspacePolicy, với method belongsToWorkspace nằm trong model User, một lối tắt khác tới roleIn. Trên màn hình, roleIn chạy thêm một Eloquent query trên memberships() theo workspace_id rồi trả về role (hoặc null), còn belongsToWorkspace trả về true khi roleIn khác null.

Đó là cách bạn bảo vệ MCP server và tool khỏi người dùng chưa authenticate, và bảo vệ một workspace cụ thể trong hệ thống multi-tenancy khỏi một trong các tham số, ở đây là tham số trên URL, chính URL bạn đã đưa vào lệnh thêm MCP server cho Claude Code.

14. Tóm lại bài đầu tiên

Đây mới là ví dụ tổng quan đầu tiên: người dùng Alice có MCP server riêng gắn với token riêng của cô, và làm việc trên task cùng dữ liệu trong workspace của cô. Povilas hy vọng từ đây người xem nắm được MCP hoạt động ra sao nói chung, trước khi đi vào các ví dụ sâu hơn trong phần còn lại của khoá học.