Arcade MCP Agent Platform

开放代理平台 + 街机MCP（多控制平台）

一个基于LangChain开放代理平台和Arcade MCP网关的、可投入生产的代理管理平台

🤖 LangGraph 代理（或：智能体） • 🔧 街机MCP工具 • 🚀 准备就绪，迎接企业级应用

快速入门 • 建筑学 • 配置 • 文档

______________________________________________________________________

概述

这之所以特别的原因

• 🔐 多供应商单点登录（Multi-Provider SSO）Okta、Microsoft Entra ID 和 PingID - 选择您的身份提供商
• 🛠️（工具或修理的象征） 通过游戏机获取100+种工具GitHub、Slack、Gmail、日历、Linear 等更多工具
• 🔒（锁形符号，常用于表示安全、保密或锁定状态） 自定义验证器具备用户验证功能的生产就绪OAuth安全方案
• ⚡（闪电符号，无直接对应中文翻译，可保留原样或根据上下文解释为“闪电”等意象） 代理架构无客户端凭据，完全控制请求
• 🎯 目标（靶心） 真正的多用户基于会话的身份进行的用户级工具授权
• 🏢（企业/公司） 企业就绪实现完整的单点登录（SSO）集成，同时提供防钓鱼和会话劫持保护

关键特性

✨ 代理管理

通过直观的网页界面构建和配置LangGraph代理。无需编写代码即可完成代理的部署和配置。

🔧 街机MCP（多协议控制器）集成

访问Arcade的完整工具生态系统：

• 生产力Gmail，Google日历，Outlook，Notion，Asana
• 开发者工具GitHub，Jira，Linear
• 交流Slack、Microsoft Teams、Discord
• 以及1000多个更多……完整列表： docs.arcade.dev/en/mcp-servers 翻译为中文是：“docs.arcade.dev 网站上的 MCP 服务器（英文）页面”。不过，为了更自然地表达，我们可以稍作调整，翻译为：“docs.arcade.dev 网站中关于 MCP 服务器的英文文档页面”。

🔐 安全工具授权

• 自定义验证器端点在OAuth流程中验证用户身份
• 服务器端API密钥从未暴露给浏览器
• 每个用户的OAuth（开放授权）每个用户都使用自己的账户授权工具
• 钓鱼攻击/会话劫持防护确保会话用户与授权用户一致
• 多用户隔离用户无法访问彼此的工具授权
• 已准备好投入生产实施；实现 街机的安全要求

💬 高级聊天界面

• 实时流式响应
• 工具执行可视化
• 多模态支持（文本、图片、文件）
• 线程历史记录与管理

🎨 无代码配置

• 可视化工具选择界面
• 通过UI表单进行代理配置
• 模型选择和参数调优
• MCP服务器配置

建筑

┌──────────────────────────────────────────────────────────────────────┐
│                         Browser (Client)                             │
│  ┌────────────┐    ┌──────────────┐    ┌──────────────────────────┐  │
│  │  Chat UI   │    │  Tools UI    │    │  Agent Management        │  │
│  └──────┬─────┘    └──────┬───────┘    └──────────┬───────────────┘  │
│         │                 │                       │                  │
│         └─────────────────┴───────────────────────┘                  │
│                           │                                          │
│                 User authenticated via:                              │
│                 Okta / Entra ID / PingID                             │
│                            │                                         │
└────────────────────────────┼─────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────────┐
│              Next.js Backend (Server) + NextAuth                    │
│                                                                     │
│  ┌─────────────────────┐  ┌──────────────────┐  ┌────────────────┐  │
│  │ /api/auth/          │  │ Session Mgmt     │  │ /api/arcade/   │  │
│  │ [..nextauth]        │  │ (JWT Cookies)    │  │ verify         │  │
│  │                     │  │                  │  │                │  │
│  │ • Okta OIDC         │  │ Gets user email  │  │ Custom         │  │
│  │ • Entra ID OIDC     │  │ from session     │  │ Verifier       │  │
│  │ • PingID OIDC       │  │                  │  │ (Phase 3)      │  │
│  └─────────────────────┘  └────────┬─────────┘  └────────┬───────┘  │
│                                    │                     │          │
│  ┌─────────────────────┐  ┌────────▼──────────┐          │          │
│  │ /api/langgraph/     │  │ /api/oap_mcp      │◄─────────┘          │
│  │ proxy/{id}          │  │                   │  (on OAuth redirect)│
│  │                     │  │ Gets session:     │                     │
│  │ Injects:            │  │ user.email        │                     │
│  │ • LANGSMITH_API_KEY │  │                   │                     │
│  │ • x-auth-scheme     │  │ Injects:          │                     │
│  └──────────┬──────────┘  │ • Authorization:  │                     │
│             │             │   Bearer ${KEY}   │                     │
│             │             │ • Arcade-User-ID: │                     │
│             │             │   ${session.email}│                     │
│             │             └─────────┬─────────┘                     │
└─────────────┼───────────────────────┼───────────────────────────────┘
              │                       │
              ▼                       ▼
┌───────────────────────┐   ┌─────────────────────────────────────────┐
│  LangGraph Deployment │   │      Arcade MCP Gateway                 │
│                       │   │                                         │
│  • localhost:2024     │   │  1. Receives tool call with             │
│  • LangSmith Cloud    │   │     Arcade-User-ID: user@company.com    │
│                       │   │  2. User needs GitHub OAuth?            │
│  Executes agents with │   │  3. Redirects to GitHub                 │
│  configured MCP tools │   │  4. User authorizes                     │
│                       │   │  5. Redirects to /api/arcade/verify     │
│                       │   │  6. Verifier confirms user identity     │
│                       │   │  7. Tool authorized for this user       │
│                       │   │  8. Executes with user's OAuth token    │
└───────────────────────┘   └─────────────────────────────────────────┘

数据流

用户身份验证与会话流程（第二阶段）

1. User visits OAP → Unauthenticated
2. Middleware checks session → None found
3. Redirect to SSO login page (Okta/Entra/Ping)
4. User authenticates with corporate SSO
5. SSO redirects to /api/auth/callback/{provider}
6. NextAuth validates OAuth code & creates JWT session
7. Session cookie stored (httpOnly, secure)
8. User redirected to OAP → Authenticated
9. All subsequent requests include session cookie

MCP工具执行与多用户认证（阶段2和3）

1. User A (alice@company.com) → Agent: "Check my GitHub repos"
2. Agent → LangGraph: Invokes GitHub tool
3. LangGraph → OAP /api/oap_mcp
4. OAP extracts session: alice@company.com
5. OAP → Arcade with headers:
   • Authorization: Bearer ${ARCADE_API_KEY}
   • Arcade-User-ID: alice@company.com
6. Arcade checks: Does alice@company.com have GitHub OAuth?
   
   If NO:
   7a. Arcade → User's browser: GitHub OAuth page
   7b. User authorizes with THEIR GitHub account
   7c. GitHub → Arcade with auth code
   7d. Arcade → OAP Custom Verifier: /api/arcade/verify?flow_id=xxx
   7e. Verifier gets session email: alice@company.com
   7f. Verifier → Arcade: confirmUser(flow_id, alice@company.com)
   7g. Arcade validates identity match ✓
   7h. Tool authorized for alice@company.com
   
   If YES:
   7. Use existing OAuth token
   
8. Arcade → GitHub API with alice@company.com's token
9. GitHub returns Alice's repos
10. Arcade → OAP → Agent → User: Alice sees HER repos

// Meanwhile, User B (bob@company.com) has separate auth
// Bob's tools use BOB's GitHub account, completely isolated

动态标题（多用户）

// Sent to Arcade on every MCP request - dynamically per user
Authorization: Bearer arc_proj... // Same for all (project key)
Arcade-User-ID: alice@company.com  // Different per user from session!

快速入门

先决条件

• Node.js 18岁以上，以及 纱线
• python 3.10+（针对LangGraph代理）
• LangGraph CLI: pip install langgraph-cli
• 街机账号在……注册 arcade.dev（可译为“街机开发平台”或根据具体语境译为其他更贴切的名称，但在此直接保留原英文形式以体现其专有名词性质）
• LangSmith 账户在（网站/平台）注册 smith.langchain.com（可译为：史密斯的语言链网站，但通常网址不直接翻译，保持原样或根据具体语境稍作调整）
• Anthropic API密钥来自……（获取/取自） console.anthropic.com（可译为：“Anthropic控制台网址”或根据具体语境简化为“Anthropic控制台”，但直接作为网址名称时，通常保持原样）
• 单点登录（SSO）提供者 （选择一个）：Okta、Microsoft Entra ID 或 PingID 帐户

步骤1：设置Arcade MCP网关

1. 创建一个街机游戏账户 在 arcade.dev（可译为“街机开发平台”或保持原样，具体取决于上下文和目标受众，若作为网站名称，通常直接保留原名）
2. 获取您的API密钥 来自Arcade仪表板
3. 记下您的MCP网关URL： https://api.arcade.dev/mcp/
4. 配置工具 你想使用（GitHub、Slack 等）

步骤2：创建一个LangGraph代理

# Use the example agent included
cd simple-langgraph-agent

# Install dependencies
pip install -r requirements.txt

# Add your Anthropic API key
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# Start the LangGraph server
langgraph dev --port 2024

当服务器启动时， 记下助手的ID 显示在输出或LangSmith Studio的URL中。

步骤3：配置单点登录（SSO）提供商

选择一个（或多个）身份提供商：

选项A：Okta

# In Okta Dashboard, create OIDC Web App
# Redirect URI: http://localhost:3000/api/auth/callback/okta
# Copy: Client ID, Client Secret, Issuer

选项B：Microsoft Entra ID

# In Azure Portal, create App Registration
# Redirect URI: http://localhost:3000/api/auth/callback/entra-id
# Copy: Application ID, Client Secret, Tenant ID

选项C：PingID

# In PingOne Console, create OIDC Web App
# Redirect URI: http://localhost:3000/api/auth/callback/ping
# Copy: Client ID, Client Secret, Issuer URL

步骤4：配置OAP

cd open-agent-platform/apps/web
cp .env.example .env.local

# Generate NextAuth secret
openssl rand -base64 32

# Edit .env.local with ALL required values:

完成 .env.local 示例：

# Base & NextAuth
NEXT_PUBLIC_BASE_API_URL=http://localhost:3000/api
NEXTAUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000

# SSO Provider (at least one)
PING_CLIENT_ID=
PING_CLIENT_SECRET=
PING_ISSUER=https://auth.pingone.com/{env-id}/as

# LangGraph
NEXT_PUBLIC_DEPLOYMENTS='[{"id":"","deploymentUrl":"http://localhost:2024","isDefault":true,"defaultGraphId":"chat_agent","name":"Local"}]'
NEXT_PUBLIC_USE_LANGSMITH_AUTH=true
LANGSMITH_API_KEY=lsv2_pt_...

# Arcade
ARCADE_MCP_GATEWAY_URL=https://api.arcade.dev/mcp/your-slug
ARCADE_API_KEY=arc_proj_...
NEXT_PUBLIC_MCP_AUTH_REQUIRED=true

# Optional fallback (only for dev without SSO)
# ARCADE_USER_ID=dev@example.com

第五步：运行OAP

# From project root
yarn install
yarn dev

导航至 http://localhost:3000

步骤6：验证并创建代理

1. 登录点击用户菜单 → 选择您的SSO服务提供商 → 认证
2. 浏览工具首选 /tools → 查看全部1000+款街机MCP工具
3. 创建代理首选 /agents → 点击“创建代理”
4. 选择图表从下拉菜单中选择“聊天代理”
5. 配置MCP工具选择代理可以访问的工具
6. 命名并创建给你的代理起个名字并描述一下
7. 开始聊天点击进入您的代理并开始对话！

步骤7：（可选）为生产环境配置自定义验证器

对于生产环境的多用户OAuth安全：

1. 将OAP部署到公共URL或使用ngrok
2. 首选 街机仪表盘 → 认证 → 设置
3. 选择 “自定义验证器”
4. 输入验证器URL： https://your-domain.com/api/arcade/verify
5. 保存并测试工具授权流程

看见 PHASE3-COMPLETE.md 翻译为中文是：“阶段3-完成.md” 用于详细的验证器设置。

配置

环境变量

见 apps/web/.env.example 以下是包含详细说明的完整模板。

核心变量（必填）

单点登录（SSO）提供程序（至少配置一个）

OKTA_CLIENT_SECRET OKTA_ISSUER | Okta | Okta OIDC 应用程序凭据 | | ENTRA_CLIENT_ID ENTRA_CLIENT_SECRET ENTRA_TENANT_ID | 微软 | Azure AD/Entra ID 应用注册 | | PING_CLIENT_ID PING_CLIENT_SECRET PING_ISSUER | PingID | Ping Identity OIDC 应用程序 |

街机MCP（必需）

LangGraph（必需）

LangGraph 部署配置

这个（或“该”） NEXT_PUBLIC_DEPLOYMENTS 是一个JSON数组。 重要提示： 这个（或“该”） id 字段必须是 助手ID，而不是一个随机的UUID。

[{
  "id": "LANGGRAPH_ASSISTANT_ID_HERE",            // Assistant ID from langgraph dev
  "deploymentUrl": "http://localhost:2024",       // Where LangGraph is running
  "isDefault": true,                              // Whether this is the default
  "defaultGraphId": "chat_agent",                 // Graph ID from langgraph.json
  "name": "Local Development"                     // Display name
}]

查找您的助手ID：

# Start your LangGraph agent
langgraph dev --port 2024

# Look for the assistant ID in the LangSmith Studio URL, or:
curl http://localhost:2024/assistants/search | jq

它是如何工作的

街机MCP（多控制平台）集成

服务器端代理模式

所有MCP请求都通过Next.js后端进行代理，以保护API密钥：

// Browser makes request to local endpoint
const client = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/api/oap_mcp")
);

// Server proxies to Arcade with auth headers
headers.set("Authorization", `Bearer ${ARCADE_API_KEY}`);
headers.set("Arcade-User-ID", ${ARCADE_USER_ID});

// Request forwarded to Arcade
fetch("https://api.arcade.dev/mcp/yourslug", { headers });

用户级工具授权

Arcade 为每个工具处理 OAuth：

1. 用户通过Arcade的OAuth流程授权一个工具（例如，GitHub）
2. 街机游戏将与用户电子邮件关联的授权信息存储起来
3. 当工具被调用时， Arcade-User-ID 头部标识出是哪个用户
4. Arcade 使用该用户的 OAuth 令牌来执行工具
5. 结果返回给代理

这意味着每个用户都可以拥有自己独立的GitHub/Slack等授权。

认证架构

当前实施阶段（第二阶段）

NextAuth + 多提供商单点登录（SSO） 支持多个企业身份提供商的生产就绪认证：

支持的提供者：

• Okta（通常作为专有名词保留不变，不直接翻译） - 企业单点登录（SSO）平台
• Microsoft Entra ID（注：在中文语境中，通常直接使用其英文原名，但为符合中文表达习惯，可理解为“微软Entra身份标识”或“微软Entra ID服务”，不过更常见的还是直接沿用英文名称） （原名为Azure AD）- 微软的身份验证平台
• PingID - Ping Identity 单点登录（SSO）解决方案

开发模式 （NODE_ENV=development)：

• 可选认证 - 允许在无单点登录（SSO）的情况下进行测试
• 如果失败则回退到 ARCADE_USER_ID 来自环境
• 登录按钮可用但非必需
• 与第一阶段完全向后兼容

生产模式 (NODE_ENV=production)：

• 访问需要SSO（任何已配置的提供商均可）
• 用户使用其企业身份提供商进行身份验证
• 按用户授权的街机工具
• 会话通过安全的JWT（JSON Web Token）Cookie进行管理

实施：

// apps/web/src/lib/auth/auth.ts - Dynamic provider configuration
const getProviders = () => {
  const providers = [];
  
  // Okta
  if (process.env.OKTA_CLIENT_ID && process.env.OKTA_ISSUER) {
    providers.push({ id: "okta", type: "oidc", ... });
  }
  
  // Microsoft Entra ID
  if (process.env.ENTRA_CLIENT_ID && process.env.ENTRA_TENANT_ID) {
    providers.push({ id: "entra-id", type: "oidc", ... });
  }
  
  // PingID
  if (process.env.PING_CLIENT_ID && process.env.PING_ISSUER) {
    providers.push({ id: "ping", type: "oidc", ... });
  }
  
  return providers;
};

// apps/web/src/app/api/oap_mcp/proxy-request.ts  
// Multi-user support - each user's email from their SSO session
const session = await auth();
const userEmail = session?.user?.email || ARCADE_USER_ID_FALLBACK;
headers.set("Arcade-User-ID", userEmail);

好处：

• 多供应商灵活性 - 选择您的企业单点登录（SSO）提供商
• 按用户访问工具 - 每个用户都有自己的Arcade OAuth授权
• 安全的 - 来自已验证的JWT会话的电子邮件，而非客户端输入
• 零配置默认值 - 仅配置您需要的提供者
• 企业级就绪 - 标准OIDC协议，可与任何OIDC提供者配合使用

LangGraph 代理模式

所有LangGraph请求均使用服务器端身份验证：

// Client creates SDK client pointing to proxy
const client = new Client({
  apiUrl: "http://localhost:3000/api/langgraph/proxy/{deploymentId}",
  defaultHeaders: { "x-auth-scheme": "langsmith" }
});

// Server uses LangSmith API key (never exposed to client)
const headers = {
  "Authorization": `Bearer ${LANGSMITH_API_KEY}`,
  "x-auth-scheme": "langsmith"
};

福利：

• 没有客户端凭据
• 集中式身份认证管理
• 易于轮换API密钥
• 与企业安全策略兼容

项目结构

open-agent-platform/
├── apps/
│   ├── web/                          # Main Next.js application
│   │   ├── src/
│   │   │   ├── app/
│   │   │   │   ├── (app)/            # Main app routes
│   │   │   │   │   ├── agents/       # Agent management
│   │   │   │   │   ├── tools/        # Tool browser & playground
│   │   │   │   │   └── layout.tsx    # Root layout with providers
│   │   │   │   └── api/
│   │   │   │       ├── oap_mcp/      # 🎯 Arcade MCP proxy
│   │   │   │       │   ├── route.ts
│   │   │   │       │   └── proxy-request.ts  # Header injection
│   │   │   │       └── langgraph/
│   │   │   │           ├── proxy/    # LangGraph proxy
│   │   │   │           └── defaults/ # Default assistants
│   │   │   ├── components/           # Reusable UI components
│   │   │   ├── features/             # Feature modules
│   │   │   │   ├── agents/           # Agent CRUD operations
│   │   │   │   ├── chat/             # Chat interface
│   │   │   │   └── tools/            # Tool management
│   │   │   ├── hooks/
│   │   │   │   ├── use-mcp.tsx       # 🎯 MCP client hook
│   │   │   │   └── use-agents.tsx    # Agent operations
│   │   │   ├── lib/
│   │   │   │   ├── auth/
│   │   │   │   │   ├── types.ts      # Auth interfaces
│   │   │   │   │   ├── mock-provider.ts  # 🎯 Mock auth
│   │   │   │   │   └── middleware.ts # Request middleware
│   │   │   │   └── client.ts         # LangGraph SDK factory
│   │   │   └── providers/
│   │   │       ├── Session.tsx       # 🎯 Session context
│   │   │       ├── MCP.tsx           # 🎯 MCP context
│   │   │       └── Agents.tsx        # Agents context
│   │   └── .env.example              # 🎯 Configuration template
│   └── docs/                         # Documentation site
│
├── simple-langgraph-agent/           # 🎯 Example agent for testing
│   ├── agent.py                      # Minimal agent with MCP support
│   ├── langgraph.json               # LangGraph configuration
│   └── requirements.txt
│
├── PHASE1-COMPLETE.md                # 🎯 Phase 1 implementation notes
└── README.md                         # This file

🎯 = Modified/created for Arcade integration

发展

本地运行

1号航站楼 - LangGraph 代理：

cd simple-langgraph-agent
langgraph dev --port 2024

第二航站楼 - 老年旅客（OAP）前端系统：

cd open-agent-platform
yarn dev

访问：

• OAP：老年人（Old Age Pensioner的缩写，或泛指老年人群体） http://localhost:3000
• LangGraph Studio： http://localhost:2024 （或通过LangSmith）

测试MCP工具

无需创建代理即可浏览和测试街机工具：

# Open in browser
http://localhost:3000/tools          # Browse all available tools
http://localhost:3000/tools/playground  # Test tool execution

创建智能体

1. 确保LangGraph代理正在运行
2. 首选 /agents 在OAP（开放访问出版/开放获取出版）中
3. 点击“创建代理”
4. 从下拉菜单中选择图表
5. 配置MCP工具
6. 创建并开始聊天！

实施细节

与原始OAP（开放访问计划/出版协议等，具体含义需根据上下文确定）的变更

已移除

• ❌ 所有Supabase认证代码
• ❌ 认证用户界面页面（登录、注册、密码重置）
• ❌ 用户管理功能
• ❌ Supabase SDK 依赖项（@supabase/ssr， @supabase/supabase-js)

添加了

• ✅ 弧形MCP网关集成
• ✅ 为Arcade认证自定义头部注入
• ✅ 模拟认证提供者
• ✅ 环境变量重命名： ARCADE_MCP_GATEWAY_URL
• ✅ 改进后的文档

修改过的

• 🔄 中间件：允许所有请求（不进行身份验证检查）
• 🔄 MCP 代理：注入特定于街机游戏的头部信息
• 🔄 客户端创建：强制仅代理模式
• 🔄 所有组件：移除会话/令牌依赖
• 🔄 RAG：已临时占位（或“已临时搁置”）

修改过的文件（摘要）

已删除（15+个文件）：

src/lib/auth/supabase.ts
src/lib/auth/supabase-client.ts
src/providers/Auth.tsx
src/app/(auth)/          # Entire directory
src/features/signin/
src/features/signup/
src/features/forgot-password/
src/features/reset-password/
src/app/debug-auth/
src/components/auth/

创建时间：

# Phase 1: Core Infrastructure
src/lib/auth/mock-provider.ts        # Mock auth for testing
src/providers/Session.tsx            # Session provider (now uses NextAuth)
apps/web/.env.example                # Configuration template
simple-langgraph-agent/              # Example LangGraph agent

# Phase 2: Multi-Provider Authentication
src/lib/auth/auth.ts                 # NextAuth config with 3 providers
src/lib/auth/providers.ts            # Provider utilities
src/app/api/auth/[...nextauth]/      # NextAuth API routes

# Phase 3: Custom Verifier
src/app/api/arcade/verify/           # Arcade custom verifier endpoint

修改过（30+个文件）：

# Core Changes
apps/web/package.json                # Removed Supabase, added NextAuth + Arcade SDK
src/app/api/oap_mcp/proxy-request.ts # Dynamic Arcade-User-ID from session
src/hooks/use-mcp.tsx                # Protocol 2025-06-18 support
src/lib/client.ts                    # Proxy-only mode
src/lib/auth/middleware.ts           # NextAuth session validation
src/components/sidebar/nav-user.tsx  # Multi-provider sign-in UI
src/providers/Agents.tsx             # Removed session dependencies
src/providers/Session.tsx            # NextAuth integration
src/app/(app)/layout.tsx             # NextAuthSessionProvider wrapper

# 25+ more files updated

故障排除

工具未加载

症状： /tools 页面为空或显示“没有可用工具”

解决方案：

1. 验证 ARCADE_MCP_GATEWAY_URL 是正确的（请查看街机仪表盘）
2. 确认 ARCADE_API_KEY 是有效的
3. 确保 ARCADE_USER_ID 与您的街机账户电子邮件匹配
4. 检查浏览器控制台中的错误
5. 查找终端日志： MCP Proxy: Forwarding request to...

常见问题：

• 协议版本不匹配 → 升级MCP SDK： yarn add @modelcontextprotocol/sdk@latest
• 404错误 → 检查URL中没有多余的斜杠 /mcp/mcp/
• 401/403 错误 → 验证API密钥和用户ID

图表下拉菜单为空

症状： “创建代理”对话框中未显示图表

解决方案：

1. 确保LangGraph代理正在运行： curl http://localhost:2024/ok
2. 验证 NEXT_PUBLIC_DEPLOYMENTS id 是的 助手ID （非随机UUID）
3. 检查 NEXT_PUBLIC_BASE_API_URL 包括 /api 后缀
4. 环境更改后重启OAP
5. 检查浏览器控制台中的“未找到部署”错误

查找助手ID：

# From LangSmith Studio URL, or:
curl http://localhost:2024/assistants/search | jq '.[0].assistant_id'

LangGraph 路由上的 404 错误

症状： 请求发送至 /langgraph/... 返回404

解决方案： 添加 /api 到 NEXT_PUBLIC_BASE_API_URL：

# Wrong:
NEXT_PUBLIC_BASE_API_URL=http://localhost:3000

# Correct:
NEXT_PUBLIC_BASE_API_URL=http://localhost:3000/api

MCP协议版本错误

症状： Server's protocol version is not supported: 2025-06-18

解决方案： 更新MCP SDK：

cd apps/web
yarn add @modelcontextprotocol/sdk@latest

当前状态与路线图

✅ 第一阶段：完成

• Supabase 认证已移除
• 街机MCP网关集成
• 仅实现了代理架构
• 用于测试的模拟认证提供者
• 完整的代理+工具功能正常运行

✅ 第二阶段：完成

NextAuth + 多提供者单点登录（SSO）集成

• ✅ NextAuth.js v5 已安装并配置
• ✅ 三个企业身份提供商：

- 使用PKCE的Okta OIDC - Microsoft Entra ID（Azure AD） - PingID与Ping Identity（结合使用）

• ✅ 动态提供商检测（零配置）
• ✅ 使用JWT会话管理进行真实身份验证
• ✅ 动态 Arcade-User-ID 来自已验证用户邮箱
• ✅ 开发模式回退（向后兼容）
• ✅ 多提供商登录界面
• ✅ 通过中间件强制执行生产认证

✅ 第三阶段：完成

街机自定义验证器

• ✅ 自定义验证器端点位于 /api/arcade/verify
• ✅ 集成街机SDK用于 confirmUser API
• ✅ 基于会话的用户身份验证
• ✅ 防止网络钓鱼攻击
• ✅ 多用户OAuth隔离
• ✅ 准生产就绪的安全实施
• ✅ 设计成功/错误页面样式
• ✅ 全面的错误处理

📋 未来改进方向

RAG的重新实现

• 通过NextAuth集成恢复RAG功能
• 每个用户的文档集合
• 经过身份验证的向量存储访问

多部署支持

• 同时部署多个LangGraph实例
• 云+本地混合部署
• 部署选择用户界面

安全与生产准备就绪

生产就绪功能 ✅

身份验证与授权：

• ✅ 多供应商单点登录（Okta、Entra ID、PingID）
• ✅ 使用JWT的NextAuth会话管理
• ✅ OAuth安全自定义验证器（适用于Arcade）
• ✅ 每个用户的工具授权
• ✅ 防止网络钓鱼攻击
• 服务器端API密钥存储

架构安全：

• ✅ 代理模式防止凭证泄露
• ✅ 无客户端令牌或密钥
• ✅ 基于会话的用户识别
• ✅ 多用户OAuth隔离
• ✅ 准备就绪以使用HTTPS（在生产环境中进行配置）

部署模式

开发模式 (NODE_ENV=development)：

• 认证可选
• 回退到 ARCADE_USER_ID 环境变量
• 非常适合本地测试
• 所有功能均正常运作

生产模式 (NODE_ENV=production)：

• 需要SSO（至少配置一个提供商）
• 用户级别的认证和工具访问
• 自定义验证器已激活
• 会话验证已强制执行

制作前检查清单

在直播前：

1. ✅（对号，表示正确、确认或完成） 认证NextAuth 配置了 SSO（阶段 2 和 3 已完成）
2. ✅ 验证者自定义验证器已实现并测试
3. ✅ 多用户按用户工具授权功能正常运行
4. ⚠️ HTTPS/TLS生产环境需配置OAuth（在托管服务上进行配置）
5. ⚠️ 域名（或领域、范围）需要真实域名（测试时使用ngrok）
6. ⚠️ 速率限制根据您的使用场景，如有需要请添加
7. ⚠️ 监测设置日志记录/警报
8. ⚠️（注意） 备份配置数据持久化策略

街机MCP参考手册

支持的工具类别

• 生产率Gmail、Google日历、Outlook、Notion、Asana、ClickUp
• 开发者GitHub、GitLab、Jira、Linear
• 交流Slack、Microsoft Teams、Discord、Zoom
• 客户关系管理（Customer Relationship Management）Salesforce，HubSpot
• 存储Google云端硬盘、Dropbox、Box
• 社交LinkedIn（领英）、Twitter/X（推特/微博客）、Reddit（一个社交新闻聚合网站）
• 还有很多其他的。。。

完整名单： docs.arcade.dev/en/mcp-servers 翻译为中文是：“docs.arcade.dev 网站上的 MCP 服务器（页面）”。不过，为了更自然地表达，我们通常会说：“在 arcade.dev 的文档中，关于 MCP 服务器的部分”。但直接翻译原网址格式，就是上述翻译。

自定义验证器实现

该平台包含一个可投入生产的自定义验证器，用于安全的多用户OAuth认证：

终端节点: /api/arcade/verify

工作原理：

1. 用户发起工具授权（例如，GitHub）
2. 街机游戏机通过外部服务处理OAuth
3. OAuth流程完成后，Arcade会重定向到验证器，并携带 flow_id
4. 从NextAuth会话中提取用户电子邮件
5. 电话 arcade.auth.confirmUser(flow_id, user_email)
6. 街机游戏验证用户身份与流程匹配
7. 工具授权安全完成

安全优势：

• ✅ 防止网络钓鱼攻击
• ✅ 验证会话用户 = OAuth 用户
• ✅ 强制实施多用户隔离
• ✅ 无法为其他用户授权工具

配置：

• 开发：使用Arcade的默认验证器
• 测试：在Arcade仪表板中配置ngrok URL
• 生产：在Arcade仪表板中配置生产域

文档： 街机自定义验证器

相关项目

• LangChain开放代理平台：

• 街机MCP（或：街机控制平台）： arcade.dev（可译为“街机开发平台”或根据具体语境保留原样，若作为网站名则通常不直接翻译）

• 模型上下文协议： modelcontextprotocol.io

许可证

见 许可证 详情请查阅文件。

致谢

• LangChain 为开放代理平台基金会（或：面向开放代理平台基金会）
• Arcade.dev（注：此名称可能是一个特定项目或平台的名称，直接翻译为中文可能不具有实际意义，因此保留原样。若需根据上下文赋予其特定含义，可译为“街机开发平台/社区”等，但具体需依据实际情况确定。） 针对MCP网关基础设施和工具生态系统

______________________________________________________________________