Laravel MCP 实战：让 AI Agent 直接操作你的 SaaS

为什么 SaaS 需要 MCP 服务器

最近围绕 MCP（Model Context Protocol）服务器的讨论在 SaaS 圈子里越来越热。来自 Laravel Daily 的这门课程背景正是源于创业圈的一个共识：MCP 正在成为 SaaS 产品的新标配。创作者观察到大量来自初创企业、SaaS 从业者和商业人士的推文，核心观点可以归纳为三类——「给你的 SaaS 加上 MCP」、「有了 MCP，界面还重要吗」、以及「MCP 已经成为是否选用某款软件的决定性因素」。

这背后的逻辑是：当用户可以通过 Claude Code、Codex 等 AI Agent 直接向你的 SaaS 发送自然语言指令时，传统的 Web UI 算是变成了「可选项」。用户不再需要打开网站点点点，而是直接在 AI 终端里描述需求并获得结果。对于任务管理、项目管理这类工具（如 Linear），这种交互方式尤其契合。

一个关键的时间节点是 Laravel MCP 包正式发布了 1.0 版本，这意味着它已经稳定、官方且可用于生产环境，为 Laravel 开发者接入 MCP 扫清了障碍。

「多租户（Multi-tenancy）」是 SaaS 架构中的核心概念，指同一套应用实例同时服务多个相互隔离的客户组织（即 tenant/workspace）。常见实现方式有三种：共享数据库共享 schema（通过 tenant_id 字段区分）、共享数据库独立 schema，以及独立数据库。无论哪种方式，数据隔离都必须在每一层严格执行——包括查询、缓存、队列、以及本文讨论的 MCP 工具调用。一旦 MCP server 缺乏租户隔离，攻击者只需猜测或枚举其他租户的 workspace ID，就能通过合法的 AI 指令跨租户读取或篡改数据，危害远比传统 API 更隐蔽，因为整个调用链由 AI Agent 自动完成，日志追踪难度也更高。

一个真实的任务管理 SaaS 演示

课程以一个贴近现实的 SaaS 为例：一款类似 Linear 的任务与项目管理应用，具备项目、优先级、负责人（涉及角色权限）以及 workspace（意味着多租户架构）。这些特性恰好代表了真实 SaaS 在接入 MCP 时必须面对的复杂性。

演示中，作者以用户 Alice 的身份在 Claude Code 里输入了一段自然语言 prompt：「我是 Alice，刚休假回来，帮我梳理一下情况，创建一个任务，分配给 Bob，并留下评论。」整个过程大约 40 秒，Claude Code 调用了名为 team board 的 MCP server，自动完成了任务创建、分配和评论，并返回了一份「欢迎回来」的总结报告。

回到 Dashboard 验证，可以看到开放任务从 5 个变成了 6 个，新建的高优先级待办确实被分配给了 Bob。这个结果既令人惊叹又略带「可怕」——AI Agent 真实地操作了数据库中的业务数据，而用户全程没有打开网站。

MCP 与传统 API 的区别

从表面看，MCP 很像 API，但它遵循一套截然不同的规则。核心差异集中在几个方面：

• 安全性与认证：谁有权调用、调用什么
• 多租户隔离：确保用户只能访问自己 workspace 的数据
• 自然语言到数据库的映射：如何把 prompt 解析成真实的查询

在实现上，Laravel MCP 的结构会让熟悉 Laravel 的开发者倍感亲切。通过 composer require laravel/mcp 安装后，再 vendor publish 出 routes/ai.php 文件。MCP server 本身可以类比为一个 API controller，而其中的每个 tool 则对应 controller 里的方法。

作者特别强调了一个容易被忽视的点：tool 的 description 至关重要。因为 Claude Code 正是依据 server 和 tool 的描述文本来自动决定是否调用它。换句话说，描述就是触发器，必须写得足够精确。

MCP（Model Context Protocol）是由 Anthropic 于 2024 年底提出的开放协议，目标是标准化 AI 模型与外部工具、数据源之间的通信方式。与传统 REST API 不同，MCP 不是由人类开发者手动构造 HTTP 请求来调用，而是由 AI Agent 根据工具的自然语言描述自主决定何时调用、传入什么参数。协议本身定义了"工具（Tool）"、"资源（Resource）"和"提示（Prompt）"三类原语，其中工具是最常用的——对应可被 AI 执行的操作。MCP 采用 JSON-RPC 2.0 作为底层通信格式，支持 stdio（本地进程）和 HTTP with SSE（远程服务）两种传输方式。正是 HTTP 传输模式让 SaaS 产品可以将 MCP 服务器部署在云端，配合 Bearer Token 认证对外开放给任意 MCP 兼容的 AI 客户端（如 Claude Code、Cursor 等），而不仅限于本地工具链。

工具的结构：schema 与验证

通过 make:mcp:tool 命令生成的工具，核心是一个 handle 方法（类似 Laravel 的 job 或 action），负责构建查询、排序和分页。而真正约束 AI 输入输出的，是两个关键方法：schema 和 outputSchema。

schema 定义了从 Claude Code 请求中解析出的参数及其描述与验证规则；outputSchema 则定义返回的数据结构。值得关注的是，MCP tool 内部可以直接复用 Laravel 开发者熟悉的能力——request、validate 验证规则、以及 Gate 做权限判断。这也意味着这门课算是成了一堂 Laravel 重构课：如何让同一套业务逻辑同时服务于 Web 和 MCP server，实现代码复用。

当作者展开请求详情时，可以清楚看到人类语言被解析成结构化参数，再返回结构化数据的全过程。

认证与多租户安全防护

认证部分，课程先采用 Laravel Sanctum（后续会切换到 Laravel Passport 以获得更安全、更便捷的方案）。作者在 starter kit 默认基础上，专门构建了一个 MCP access 设置页面，让每个用户（如 Alice）生成自己的访问 token。

连接 Claude Code 的方式是通过 claude mcp add http，配合 Laravel Herd 的 secure 命令启用 HTTPS，并带上从设置页获取的 Bearer Token。连接成功后即可在 Claude Code 中看到对应的 MCP server 和其启用的工具。

安全防护是整个演示的亮点。作者模拟了一个攻击场景：如果 Alice 试图猜测其他用户的 workspace ID 和 actor ID 去窃取数据会怎样？结果 MCP server 直接返回了验证错误——workspace id field not supported here。这是 schema 层的第一道防线。

在此之上还有第二道防线：middleware（中间件）。路由中的 resolve mcp workspace 中间件会从 URL 路由中获取用户的 workspace，并将其放入 Laravel 的 Context（这正是 Context 功能的主要用途之一）。随后 list task 工具通过 workspace policy 的 belongsToWorkspace 方法，验证当前已认证用户是否真的有权访问该 workspace，底层则对应到用户 memberships 的 Eloquent 查询。

这套「schema 验证 + 中间件 + policy 授权」的组合拳，构成了保护 MCP server 免受未授权访问、并实现多租户隔离的完整方案。

Laravel Sanctum 与 Laravel Passport 在 OAuth 能力上存在显著差异，这在 MCP 场景下尤为关键。Sanctum 主要面向 SPA 和移动端的简单 token 认证，生成的是不带过期时间的「个人访问令牌（Personal Access Token）」，管理粒度较粗；而 Passport 基于完整的 OAuth 2.0 实现，支持令牌过期、令牌作用域（Scopes）、客户端凭证授权等企业级特性。在多租户 MCP 场景中，Passport 的 Scope 机制可以精确限定某个 token 只允许访问只读工具或特定 workspace，从而在 token 层面就完成一次权限收口，而不必完全依赖应用层的 policy 逻辑。这也是课程后续要从 Sanctum 升级到 Passport 的核心原因——为生产环境的 MCP 服务器提供更细粒度、更易撤销的认证方案。

小结

这段内容是一门更完整课程的前三课精华，核心目标是帮开发者建立 MCP 的整体认知：它既像 API 又不同于 API，重点在于认证、多租户隔离与自然语言到数据的安全映射。对于正在考虑给 SaaS 产品接入 AI Agent 能力的 Laravel 开发者而言，Laravel MCP 1.0 的稳定发布与这类实战范例，提供了一条清晰可落地的路径。更深入的话题——如 Laravel Passport 认证和更复杂的验证——则留在了完整课程中。