sqlite-notes
基于 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: Notebook MCP Server
1. 配置 Stytch
创建一个 Consumer Authentication 项目,然后配置:
在 Frontend SDK 中,启用 SDK 并授权
http://localhost:3000。在 Redirect URLs 中,为登录和注册都添加
http://localhost:3000/authenticate。启用 Email Magic Links,选择 Login or Create。
在 Connected Apps 中,将 Authorization URL 设置为
http://localhost:3000/oauth/authorize。启用 Dynamic Client Registration。MCP 客户端使用 DCR,因为其回调端口可能变化。
在 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 对用户进行身份验证,而你的数据库和服务决定该用户可以访问哪些行和执行哪些操作。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Build, verify and deploy full-stack apps: Postgres, sign-in, workflows, realtime, AI, rollback.
Search and read your own notes: insights, drafts, book and podcast notes. Read-only, OAuth.
Kanban tasks and project notes for AI clients, with OAuth and per-project read or write grants.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenancePersonal note management server that enables creating, reading, updating, deleting, listing, and searching notes with support for titles, content, and tags.-
- FlicenseNot gradedqualityDmaintenanceEnables to create notebooks and notes with tags, and perform full-text search across notes using FTS5 syntax, all stored locally in SQLite.-
- AlicenseNot gradedqualityDmaintenanceA local notes app that enables AI tools to manage notes via MCP (list, get, create, update, delete) using the same SQLite database as the GUI.MIT
- AlicenseAqualityBmaintenanceEnables users to create, retrieve, update, delete, and full-text search a local knowledge base of notes persisted in SQLite with FTS5, exposed over stdio or authenticated Streamable HTTP. It also surfaces recent/single-note resources and prompts for summarizing notes and drafting replies.5MIT