基于 Stytch 认证的 SQLite MCP

一个刻意保持精简的远程 MCP 服务，用于学习 SaaS 集成的形态：

• FastMCP 通过 Streamable HTTP 提供六个工具。

• Stytch Connected Apps 处理 OAuth 2.1 发现、动态客户端注册（Dynamic Client Registration）、PKCE、浏览器登录、同意和令牌签发。

• 该服务根据 Stytch 轮换的 JWKS 验证每个访问令牌的签名、签发者、受众、过期时间和 openid 范围。

• SQLite 行以令牌的 sub 为键，因此每个 Stytch 用户只能看到自己的笔记。

• 即使 Stytch 客户端被意外配置了更长的访问令牌生命周期，服务器也将访问限制在 30 分钟内。

• Claude Code 插件运行固定版本的 mcp-remote 桥接器，它执行 OAuth 并将 Claude Code 连接到远程 MCP 端点。

架构

Claude Code plugin -> http(s)://MCP/mcp -> validate Stytch JWT -> per-user SQLite CRUD
         |                                      ^
         +-> Stytch discovery -> browser login/consent app -> Stytch token endpoint

浏览器应用是必需的。Stytch 托管发现、注册和令牌端点，而你的应用托管用于登录和同意的 IdentityProvider 组件。

Related MCP server: Supabase MCP Server

1. 配置 Stytch

创建一个 Consumer Authentication 项目，然后配置：

1. 在 Frontend SDK 中，启用 SDK 并授权 http://localhost:3000。

2. 在 Redirect URLs 中，为登录和注册都添加 http://localhost:3000/authenticate。

3. 启用 Email Magic Links，选择 Login or Create。

4. 在 Connected Apps 中，将 Authorization URL 设置为 http://localhost:3000/oauth/authorize。

5. 启用 Dynamic Client Registration。MCP 客户端使用 DCR，因为其回调端口可能变化。

6. 在 Stytch 允许的范围内，将 Connected Apps 访问令牌过期时间设置为 30 分钟。

服务和插件只请求 openid，因为 MCP 服务器只需要稳定的 sub 标识符。它不需要 profile 或 email 数据。

服务器在每个访问令牌的 iat 之后 30 分钟拒绝该令牌。插件使用固定版本的 mcp-remote@0.2.1 桥接器，它请求 MCP 受保护资源通告的范围，而不添加 offline_access。因此 Stytch 不会签发刷新令牌，过期后用户将回到交互式授权。

这个桥接器是刻意为之的。原生 Claude Code OAuth 会在授权服务器通告 offline_access 时自动添加它，从而允许静默刷新令牌，使强制登录要求失效。

将 .env.example 复制为 .env 并设置：

• STYTCH_PROJECT_ID：project-test-... 项目 ID，用作 JWT 受众。

• STYTCH_DOMAIN：Stytch 显示的完整项目域名，例如 https://...customers.stytch.dev，用作签发者和 JWKS 主机。不要在此处使用 API 密钥或公共令牌。

• STYTCH_PUBLIC_TOKEN：登录和同意 UI 使用的浏览器安全 public-token-test-... 值。

• MCP_BASE_URL：MCP 服务器的外部可见源，不含 /mcp。

本项目不包含任何 Stytch 密钥。JWT 验证只需要公共签名密钥。

保存仪表板配置后，验证 Stytch 发现和签名密钥：

set -a; source .env; set +a
uv run python scripts/check_stytch.py

在打印出 PASS: Stytch authorization metadata and JWKS are ready for MCP OAuth. 之前，不要继续浏览器登录测试。

2. 本地运行

uv sync
set -a; source .env; set +a
uv run mcp-auth

在另一个终端中：

cd web
npm install
npm run dev

要进行真正的 OAuth 测试，MCP 端点和授权页面通常都应通过稳定的 HTTPS URL 访问。开发隧道可以发布 8000 和 3000 端口。将 MCP_BASE_URL、Stytch Frontend SDK 授权环境和重定向 URL、Connected Apps Authorization URL 以及 SQLITE_NOTES_MCP_URL 更新为这些 HTTPS URL。纯 localhost 设置在构建时很有用，但生产环境必须使用 HTTPS。

3. 安装并认证 Claude Code 插件

从仓库根目录注册本地市场并为该项目安装插件：

claude plugin marketplace add "$PWD" --scope project
claude plugin install sqlite-notes@mcp-auth-local --scope project

本地服务器 URL 默认为 http://127.0.0.1:8000/mcp。对于托管或隧道服务器，请在启动 Claude Code 之前设置 URL：

export SQLITE_NOTES_MCP_URL=https://your-mcp-tunnel.example/mcp

然后运行 /reload-plugins，打开 /mcp，选择 sqlite-notes。固定版本的 mcp-remote 桥接器通过 MCP 服务器发现 Stytch 授权服务器，自行注册，打开浏览器，使用 PKCE，并返回访问令牌。

尝试以下提示：

• "创建一篇标题为 Grocery list、正文为 coffee and oranges 的笔记。"

• "列出我的笔记。"

• "更新笔记 1，添加 milk。"

• "删除笔记 1。"

30 分钟后，MCP 服务器拒绝当前访问令牌。由于桥接器不请求 offline_access，它无法静默刷新，必须重复交互式授权。

测试

uv run pytest
cd web && npm run build

自动化测试涵盖 CRUD、跨用户隔离以及 30 分钟访问令牌边界。没有配置好的 Stytch 项目和电子邮件收件箱就无法自动化完整登录，因此浏览器流程是明确的手动端到端检查。

生产环境注意事项

SQLite 和单进程是本次练习的刻意选择。对于付费的多实例服务，请使用托管数据库、迁移、备份、HTTPS、结构化审计日志、速率限制和明确的授权范围。保持相同的边界：Stytch 对用户进行身份验证，而你的数据库和服务决定该用户可以访问哪些行和执行哪些操作。