AI 聽不懂你的資料庫？Laravel MCP 實戰：2026 年後端工程師必備的 AI 通訊標準

快速結論：Laravel 要怎麼接上 MCP？

Model Context Protocol（MCP）是一套標準化協定，讓 AI 模型能以一致的方式存取你後端的資料與功能，不必再為每個模型手寫專屬的 Function Calling 文件。在 Laravel 中，你只要把資料封裝成「Resource（唯讀資料）」、把動作封裝成「Tool（可執行的操作）」，再透過一個 MCP 端點對外提供，AI 客戶端就能「隨插即用」。

本文用一個產品目錄與訂單查詢的範例，帶你走完三個步驟：定義 Resource、打造 Tool、註冊並做好權限與安全控管。重點不在「讓 AI 看得到全部資料」，而在於「精準地只開放它需要的那一塊」。

提醒：本文的套件名稱、版本與部分數據沿用原作者 Eric 的示範情境，屬於概念性教學範例。實際導入時請以你採用的官方 / 社群套件的真實 API 為準，文中程式碼用來說明「設計思路」，而非可直接複製貼上的正式版本。

什麼是 MCP？為什麼後端工程師需要它？

在 AI 還沒有共通協定之前，要讓 ChatGPT 或 Claude 讀懂公司的資料庫，工程師得手寫一堆 JSON Schema，還要針對不同模型寫不同的 Prompt 來解釋 API 格式。只要資料庫欄位一改，整個 AI Agent 就跟著壞掉。

MCP 的定位很好懂：它像是「AI 時代的 USB 介面」。只要你的後端支援 MCP，理論上任何支援該協定的 AI 客戶端都能用同一種方式連上你的資料與工具，而不必為每個模型重寫一套整合。

MCP 解決了哪三個核心問題？

• 標準化介面：不再各寫各的 Function Calling，而是統一用 Resource（資料）與 Tool（工具）兩種原語來描述能力。
• 上下文管理：伺服器可以主動提供當前環境的 Context，讓 AI 不再瞎子摸象。
• 通用性：寫一次 MCP Server，理論上可同時給 IDE 內的 AI 助理、公司客服機器人或本地端的 AI 工具使用。

對 Laravel 開發者而言，這代表你不必為了 AI 特地維護一套獨立的 REST API，而是直接沿用最熟悉的 Eloquent ORM 來封裝資料來源。

MCP 的底層長什麼樣子？

理解協定的骨架，有助於你在出錯時知道該往哪裡查。MCP 在通訊上採用 JSON-RPC 風格的訊息往返，雙方是「客戶端（AI 應用）」對「伺服器（你的後端）」的關係。協定定義了幾種伺服器可對外提供的原語，最常用的是：

• Resources：提供給模型「讀取」的內容，類似唯讀的資料來源。
• Tools：可被模型「呼叫執行」的動作，會帶有輸入參數並回傳結果。
• Prompts：預先定義好的提示樣板，讓模型以一致的方式發起特定任務。

在傳輸層，MCP 常見的兩種方式是本機的標準輸入輸出（stdio），以及適合遠端連線的 HTTP 串流（例如以 Server-Sent Events 推送伺服器事件）。本機工具多半走 stdio，而像 Laravel 這種需要對外服務的後端，通常會選擇 HTTP 串流的端點。

環境準備與安裝

本文示範情境假設的開發環境如下：

• PHP 8.5+
• Laravel 11.x 或 12.x
• Composer

範例使用社群維護的 laravel-mcp 套件（這是教學情境中假設的套件，概念上對應於 MCP 的 SDK 實作）。安裝與發布設定檔：

composer require native-php/laravel-mcp

php artisan vendor:publish --tag=mcp-config

請特別注意：套件名稱與指令僅為示範，導入前務必先確認你實際採用的套件文件，安裝指令與設定標籤可能不同。

第一步：定義你的 AI 資源（Resource）

Resource 是讓 AI「讀取」資料的原語。假設你想讓 AI 能查閱公司的產品列表，在 Laravel 中這通常對應到一個 Eloquent Model。

下面建立一個 ProductResource。這裡有個重要的設計原則：雖然可以直接回傳整個 Model，但為了節省 Token 並保護隱私，應該明確挑選欄位，而不是把整張表的所有欄位都吐出去。

namespace App\Mcp\Resources;

use App\Models\Product;
use Native\Mcp\Contracts\Resource;
use Native\Mcp\Attributes\ExposeResource;

#[ExposeResource(name: 'products', description: '公司目前的產品目錄，包含庫存與價格資訊')]
class ProductResource implements Resource
{
    public function fetch(array $params = []): array
    {
        // 一定要做分頁或限制數量，不要讓 AI 一口氣拉走十萬筆資料
        return Product::query()
            ->select(['id', 'name', 'price', 'stock_quantity'])
            ->where('is_active', true)
            ->limit(20)
            ->get()
            ->toArray();
    }
}

關鍵在那個 #[ExposeResource] 屬性。它讓你不必另外維護一份 JSON 文件——這段 PHP 程式碼本身，連同它的 name 與 description，就成了 AI 理解這項資源的說明書。description 寫得越清楚，模型越能正確判斷何時該用它。

第二步：打造 AI 工具（Tool）

Resource 是唯讀的；如果要讓 AI 替你「做事」（例如查詢訂單狀態），就需要 Tool。下面寫一個 CheckOrderStatus。

namespace App\Mcp\Tools;

use App\Models\Order;
use Native\Mcp\Contracts\Tool;
use Native\Mcp\Attributes\ExposeTool;

#[ExposeTool(
    name: 'check_order_status',
    description: '根據訂單編號查詢目前的物流狀態與付款情形'
)]
class CheckOrderStatus implements Tool
{
    public function handle(array $arguments): array
    {
        $orderId = $arguments['order_id'] ?? null;

        if (!$orderId) {
            return ['error' => '請提供訂單編號'];
        }

        $order = Order::find($orderId);

        if (!$order) {
            return ['error' => '找不到該訂單'];
        }

        return [
            'status' => $order->status,
            'payment' => $order->payment_status,
            'shipping_date' => $order->shipped_at?->format('Y-m-d') ?? '尚未出貨',
        ];
    }
}

這裡善用了 PHP 的型別系統：MCP Server 可以讀取 handle 方法的參數定義，自動描述出這個工具需要哪些輸入，等於告訴 AI「要用這個工具，請給我一個 order_id」。

Resource 與 Tool 該怎麼選？

原則上：只是「給 AI 看」的就用 Resource；需要「叫 AI 做」的才用 Tool。把讀寫分開，後續的權限控管會清楚很多。

第三步：註冊、權限與安全性配置

這一步最關鍵。讓 AI 能存取後端，最怕的就是因為模型誤判而執行了不該執行的操作。因此在設定檔中，除了註冊資源與工具，更要把驗證與頻率限制設好。

// config/mcp.php

return [
    'server_name' => 'RoamerTech_Core_API',

    'resources' => [
        App\Mcp\Resources\ProductResource::class,
    ],

    'tools' => [
        App\Mcp\Tools\CheckOrderStatus::class,
    ],

    // 資安重點：一定要開啟請求驗證
    'security' => [
        'middleware' => ['auth:sanctum', 'throttle:60,1'], // 限制每分鐘 60 次請求
        'log_activity' => true, // 記錄 AI 的所有操作
    ],
];

接著設定一個對外的端點讓 MCP 客戶端連線：

// routes/api.php

Route::post('/mcp/v1/message', [McpController::class, 'handle'])
    ->middleware('auth:sanctum');

導入 MCP 必守的安全清單

1. 最小權限原則：只開放這次任務真正需要的 Resource 與 Tool，不要把所有 Model 都掛上去。
2. 強制身份驗證：端點掛上認證中介層（例如 Laravel Sanctum 或 Passport），不要裸奔對外。
3. 欄位過濾：Resource 一律明確 select 需要的欄位，避免把敏感資料一起吐出去。
4. 限制資料量：查詢務必分頁或 limit，避免一次拉走整張表，也能省下大量 Token。
5. 頻率限制：套用 throttle，防止異常的高頻呼叫拖垮資料庫。
6. 禁開危險操作：不要把刪除、清空等破壞性動作做成 Tool；真的需要時，至少加上人工確認或軟刪除。
7. 稽核記錄：開啟操作日誌，事後能追查 AI 究竟呼叫了什麼、改了什麼。

實際測試：讓 AI 與你的 Laravel 對話

啟動 Laravel 伺服器：

php artisan serve

接著在你的 MCP 客戶端設定檔中加入這個伺服器資訊。當使用者詢問「幫我查一下某張訂單的狀況，順便看看目前最貴的產品是什麼？」時，背後的流程大致是：

1. AI 分析意圖，判斷需要查訂單，也需要看產品目錄。
2. AI 透過 MCP 呼叫 check_order_status 工具，並帶上訂單編號。
3. Laravel 回傳結構化的 JSON 資料。
4. AI 接著讀取 products 這個 Resource。
5. AI 把這些原始資料整合，用自然語言回覆使用者。

整個過程中，你的後端只負責「提供精準、受控的資料與動作」，而把「如何組織語言、如何串起多步驟」交給 AI——這正是 MCP 想達成的分工。

實戰心得：從寫 Prompt 到定義知識邊界

建立第一個 Laravel MCP Server 其實不難，真正難的是「界線」的拿捏。不要把所有 Model 都丟給 MCP，那非常危險。請奉行最小權限原則，只開放任務真正需要的資料與操作。

MCP 的出現，讓後端工程師的角色從「為各種模型手寫 Prompt 與整合的黑手」，逐漸轉變為「定義知識邊界與權限範圍的架構師」。把資料與動作的邊界劃清楚，AI 才能用得既好用又安全。

需要協助導入 MCP 嗎？

如果你的企業系統還在用傳統 API 跟 AI 硬接，或擔心 AI Agent 直接存取資料庫的資安風險，浪花科技可以協助你規劃安全、受控的 MCP 通訊層，把資料與動作的邊界設計清楚。

立即聯繫我們，討論你的 AI 基礎建設

延伸閱讀

• n8n、Make、Zapier 怎麼選？2026 自動化平台完整比較
• 不只會用，更要會『造』！Laravel 自訂驗證與 Middleware 黑魔法，打造無懈可擊的 API 防線
• 別再手寫 SQL 了！Laravel Eloquent ORM 完整指南：從新手入門到效能優化，一次搞懂 Active Record 的黑魔法
• 你的 Controller 還在身兼多職？導入 Service Layer，打造可維護、高彈性的 Laravel Admin 後台架構！