Nango 接入实战：让用户在聊天中添加自己的 MCP

查项目状态这件事，模型得有工具才能做。用户说：“帮我看看 demo 项目卡在哪。”模型能理解这句话，却没有入口读取项目状态。我们想补上的体验很具体：用户添加自己的项目服务，授权一次，然后回到这段对话，拿到有依据的回答。

一句话把整条路讲清楚

用户提供工具地址，Nango 保管授权凭证，你的后端选对账号并调用工具，最后把结果交给模型回答。

MCP 可以先理解成“工具菜单加点单规则”：菜单告诉客户端有哪些工具，点单规则说明参数怎么填、结果怎么收，它的正式名称是 Model Context Protocol。Nango 则提供授权与请求转发的基础设施；模型负责选择动作，后端负责执行条件，所以新工具可以在运行时接入。

图里的中间一段要留在产品里。后端保存“当前用户对应哪个外部连接”，还保存这段聊天正在等什么；授权完成后，从等待点继续。Nango 的标签帮助关联记录，具体访问权限由产品检查，这样用户换账号时，查询才能跟着换。

逐步跑通：让 demo 项目真正返回数据

先跑通“工具存在、参数正确、结果可读”，再把授权放进聊天，排错会容易很多。下面按这个顺序准备项目服务，然后走用户添加和执行的路径。

把项目查询做成一个工具

这一步把“项目卡在哪”包装成一个有名字、有参数的函数。服务只提供 get_project_brief，输入是项目标识 projectKey；我们先放入一条演示记录，把数据库和业务权限留到上线阶段补齐。

在独立目录安装依赖。这里固定 SDK v2 的包，避免把旧教程的导入方式混进来：

npm init -y
npm install --save-exact @modelcontextprotocol/server@2.3.0 @modelcontextprotocol/client@2.3.0 @modelcontextprotocol/node@2.1.1 zod@4.6.5

保存成 server.mjs，然后运行 node server.mjs：

import { createServer } from 'node:http';
import { McpServer, createMcpHandler } from '@modelcontextprotocol/server';
import { toNodeHandler, localhostHostValidation, localhostOriginValidation } from '@modelcontextprotocol/node';
import * as z from 'zod/v4';

const projects = { demo: {
  name: '演示项目', status: '等待验收',
  blockers: ['移动端登录回归尚未完成'], synthetic: true
} };
const handler = createMcpHandler(() => {
  const server = new McpServer({ name: 'project-brief', version: '1.0.0' });
  server.registerTool('get_project_brief', {
    description: 'Read a project status and its blockers.',
    inputSchema: z.object({ projectKey: z.string().min(1).max(64) }),
    annotations: { readOnlyHint: true }
  }, async ({ projectKey }) => {
    const project = Object.hasOwn(projects, projectKey) ? projects[projectKey] : undefined;
    return project
      ? { structuredContent: { project }, content: [{ type: 'text', text: JSON.stringify(project) }] }
      : { isError: true, content: [{ type: 'text', text: 'PROJECT_NOT_FOUND' }] };
  });
  return server;
}, { responseMode: 'json' });

const handle = toNodeHandler(handler);
const hostOK = localhostHostValidation(), originOK = localhostOriginValidation();
createServer((req, res) => {
  if (!hostOK(req, res) || !originOK(req, res)) return;
  if (req.url !== '/mcp') return res.writeHead(404).end();
  void handle(req, res);
}).listen(43173, '127.0.0.1', () => console.log('MCP: http://127.0.0.1:43173/mcp'));

这时，http://127.0.0.1:43173/mcp 就有了一份项目工具菜单。像填表说明一样的 inputSchema 规定 projectKey 必须是 1—64 字符的字符串，因此传数字会被拒绝；项目不存在则返回工具错误。structuredContent 放机器可读数据，content 放文本表示，两者都来自同一条演示记录。

服务绑定本机，并检查 Host 与 Origin；JSON 响应足够完成这次快速查询。长任务的中间通知需要另一种返回方式，这个选择先记住，后面接代理时会用到。SDK 的 HTTP 接入说明

先在本地查到 demo 项目

这一步先取得工具的真实定义，再执行一次项目查询。客户端用 tools/list 拿菜单，用 tools/call 点单；开发时先写死 projectKey: 'demo'，这样就能验证模型后面要走的那条数据路径。

保持第一个终端的服务运行，在第二个终端把下面保存为 client.mjs，执行 node client.mjs：

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const client = new Client(
  { name: 'chat-demo', version: '1.0.0' },
  { versionNegotiation: { mode: 'auto' } }
);
try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL('http://127.0.0.1:43173/mcp')
  ));
  console.log(JSON.stringify(await client.listTools(), null, 2));
  const result = await client.callTool({
    name: 'get_project_brief', arguments: { projectKey: 'demo' }
  });
  console.log(result.isError ? result.content : result.structuredContent.project);
} finally {
  await client.close();
}

先看到工具名和参数结构，再看到“等待验收”与“移动端登录回归尚未完成”，最小 demo 就跑通了。改成不存在的项目会得到 PROJECT_NOT_FOUND，传错参数类型会被校验拒绝，因此我们已经把“有工具”与“业务查询成功”分开验收。

本地实验到这里已经完整：菜单、参数和结果都走通了。接下来，把同一个工具部署成公网 HTTPS 服务，接入授权服务并发布元数据，数据库查询带上调用者权限，同时把 localhost 校验配置换成实际允许的域名与 Origin，然后再让用户添加它。

让用户把这个服务添加进聊天

这一步给聊天增加一个服务入口，后面才能发现工具。用户仍然在等 demo 项目的答案，产品可以展示“添加项目工具”，让他粘贴地址，或者从目录选择。

公网产品接收的应是远程服务地址，例如 https://mcp.example.com/mcp。localhost 指当前执行程序所在的机器；访问用户电脑里的服务，需要本地客户端或隔离运行环境。若用户带来的是需要启动的包，产品也得提供运行器，Nango Generic 不负责启动进程。

目录可以从官方 MCP Registry 读取。下面的命令可直接查看名称包含 notion 的最新条目：

curl 'https://registry.modelcontextprotocol.io/v0.1/servers?search=notion&version=latest&limit=10'

search 是名称子串匹配，所以“找一个能看项目进度的工具”需要产品自己的检索与排序。remotes 描述远程地址，packages 描述要安装的包；取下一页使用 metadata.nextCursor。产品可以缓存目录并同步停用、下架状态，因为 Registry 不保证持续在线和数据持久性。

对 demo 项目，目录和自定义 URL 最终都进入同一条连接流程。先显示发布者与真实域名，再检查接法是否匹配；目录收录本身不提供安全背书。选择服务之后，把原任务留在等待状态，别让用户授权回来还要重说问题。Registry API

给用户一个短期授权入口

这一步让用户把项目账号的访问权限交给产品使用，凭证由 Nango 保存。下面走的是远程 OAuth 路线：Nango Generic 当前要求服务支持自动客户端注册，服务让客户端登记自己叫 DCR，让服务读取客户端介绍文档叫 CIMD。

开发团队先在控制台配置一次 MCP Server OAuth2（Generic），将集成 ID 设为 user-mcp。多个用户可以通过它连接各自的服务器，但每次授权都有独立连接。固定 OAuth 客户端要另外配置对应 provider；API Key 和无认证服务也有各自的接法，不走这条 Generic OAuth 路线。

安装 npm install --save-exact @nangohq/node@0.71.12，将下面保存为 connect.mjs。设置后端环境变量 NANGO_API_KEY 和已经审核的公网 MCP_URL，运行 node connect.mjs，打开打印出的链接完成授权：

import { Nango } from '@nangohq/node';
import { randomUUID } from 'node:crypto';

const apiKey = process.env.NANGO_API_KEY, mcpUrl = process.env.MCP_URL;
if (!apiKey || !mcpUrl) throw new Error('Set NANGO_API_KEY and MCP_URL');
if (new URL(mcpUrl).protocol !== 'https:') throw new Error('MCP_URL must use HTTPS');
const nango = new Nango({ apiKey });
const { data } = await nango.createConnectSession({
  allowed_integrations: ['user-mcp'],
  tags: {
    end_user_id: 'demo-user', organization_id: 'demo-org',
    connect_request_id: randomUUID()
  },
  integrations_config_defaults: {
    'user-mcp': { connection_config: { mcp_server_url: mcpUrl } }
  }
});
console.log(data.connect_link);

这里有三样东西各管一件事。user-mcp 选择集成；标签关联用户与这一次连接请求；mcp_server_url 固定访问目标。地址要放在这个嵌套层级里，session 配置优先于前端参数，预填字段会在 Connect UI 中隐藏；不预填则由用户在授权界面填写。

这个入口像一张有效期很短的入场券，正式名称是 Connect session，当前有效期为 30 分钟。返回的 token 或 connect_link 可以交给前端，环境 API Key 留在后端；正式产品把示例用户替换为登录系统确认的身份，并保存待授权记录。

聊天界面可以用前端 SDK 打开 Connect UI，从按钮点击时先打开窗口，再异步设置 session token，以减少弹窗被拦截的情况。用户授权后，Nango 给后端送来一份回执，这种事件通知叫 webhook；后端核验完成，再通过状态查询或事件推送让原聊天继续。Nango MCP Auth

把查询接回同一段聊天

这一步把已经验证的项目查询放回用户原来的问题里。后端用刚授权的连接执行，模型拿到结果后解释 demo 项目的阻塞项，前端继续展示同一个任务。

接回聊天时，把工具定义适配到所用模型的接口。模型根据“帮我看看 demo 项目卡在哪”提出工具名和参数，后端从当前用户的记录里选择连接，校验输入后执行；返回数据再作为这次工具调用的输出交回模型，它才能围绕项目的真实阻塞项回答。

这份带编号的请求信封叫 JSON-RPC，id 用来匹配响应；业务参数是 arguments.projectKey，选外部账号用的是 connectionId。多个服务都有 search 时，后端还要用路由表区分“模型可见名字、产品连接、外部工具名”，避免选错服务。

最后让模型收到必要字段和来源，让前端收到回答与任务状态。用户应该看到查的是哪个账号、结果是否覆盖他的请求；创建待办或发送通知时，先展示目标和内容，执行后再交付对象 ID 或链接。请求只发出而没有确定结果，就显示“结果待确认”。

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';

const url = new URL(process.env.MCP_URL);
const proxyFetch = async (input, init = {}) => {
  const target = input instanceof Request ? input.url : String(input);
  if (new URL(target).href !== url.href || init.method?.toUpperCase() !== 'POST') {
    throw new Error('Unexpected MCP target or method');
  }
  const headers = new Headers({
    Authorization: `Bearer ${process.env.NANGO_API_KEY}`,
    'Provider-Config-Key': 'user-mcp',
    'Connection-Id': process.env.NANGO_CONNECTION_ID,
    'Base-Url-Override': url.href, Retries: '0',
    'Content-Type': 'application/json'
  });
  const original = new Headers(init.headers);
  for (const name of ['content-type', 'accept', 'mcp-protocol-version', 'mcp-method', 'mcp-name']) {
    if (original.has(name)) headers.set(`Nango-Proxy-${name}`, original.get(name));
  }
  return fetch('https://api.nango.dev/proxy', {
    method: 'POST', headers, body: init.body, signal: init.signal, redirect: 'error'
  });
};
const client = new Client(
  { name: 'chat-demo', version: '1.0.0' },
  { versionNegotiation: { mode: { pin: '2026-07-28' } } }
);
try {
  await client.connect(new StreamableHTTPClientTransport(url, { fetch: proxyFetch }));
  console.log(await client.listTools());
  console.log(await client.callTool({ name: 'get_project_brief', arguments: { projectKey: 'demo' } }));
} finally {
  await client.close();
}

上线前，先处理这五个坑

本地查到 demo 项目，只解决了调用问题；上线还要管住账号、网络目标和失败后的动作。

1. 授权成功，却查到了别人的项目　症状：用户查询 demo，结果来自另一个账号或组织。原因：环境级 API Key 能选择连接，但标签和参数格式不提供产品用户级、项目级权限。怎么办：每次执行都从登录身份解析连接，并在实际查询中检查资源归属；个人、公司与组织共享账号分别保存，写动作审批绑定到具体工具和参数。

2. 地址填对了，工具还是连不上　症状：授权后报 unsupported_provider、协议错误，或者请求跑向错误地址。原因：Generic 的注册条件、代理地址和协议转发是三道不同配置，远程地址还会触发授权发现与网络访问。怎么办：审核 HTTPS 目标及其发现端点，按实际协议处理请求头和返回流，给内网接入设置独立受控通道，并先完成工具发现再执行 demo 查询。

3. 一次超时，创建了两个待办　症状：用户只批准一次，系统却重复写入。原因：请求可能已成功而响应丢失，JSON-RPC 请求编号不提供业务去重，关闭连接也不撤回已发生的写入。怎么办：写入默认不盲目重试，将未知结果记为 outcome_unknown，利用上游幂等机制或业务操作记录核验，再决定重试、补偿或请用户处理。

4. 菜单有这个工具，模型却填错参数　症状：发现成功，查询时缺字段、类型错误，或者模型听从了工具结果中的额外指令。原因：输入结构可能不完整，工具名称可能重名，服务说明、只读声明和返回内容都是外部数据。怎么办：保留原 schema 做后端校验，处理嵌套与引用，把工具权限和写入批准放在执行代码里；敏感参数发给陌生服务前展示目标，同时限制调用次数与时间预算。

5. 第二次回来，又得从头开始　症状：令牌失效、参数更新或临时故障后，用户要重新授权并重说任务。原因：连接状态、聊天任务和短期执行权限有各自的生命周期，不能靠一条“连接成功”文案维持。怎么办：保存任务等待点与已完成部分，用重连恢复现有连接，刷新工具缓存；权限单过期后重新检查权限，已发出的写入单独核验，保留成果再继续。

import { Nango } from '@nangohq/node';

const nango = new Nango({ apiKey: process.env.NANGO_API_KEY });
console.log(await nango.triggerAction(
  'github-getting-started', process.env.NANGO_CONNECTION_ID,
  'get-repository', { owner: 'NangoHQ', repo: 'nango' }
));

最后，回到用户那句话

用户选工具，Nango 保管授权，后端按当前账号执行，模型读结果。

先用 demo 项目跑通菜单、参数和返回，再把授权与任务恢复接回原聊天，用户才会得到一份有依据的回答。

上线前把这五个坑处理好，并持续维护连接和工具版本，下一次“帮我看看 demo 项目卡在哪”才不用从头再来。

参考资料

• Nango 固定源码基线（6b794c6）
• 版本文件
• Nango MCP Auth：目录内与自定义服务器接入
• MCP 传输方式
• Nango Agent Sessions：连接与工具范围、会话生命周期
• 连接归属要求
• 官方 Registry API
• 服务器描述格式
• Registry 审核政策
• 目录聚合建议
• Nango Connect session API：授权会话参数
• MCP Tools：发现、输入结构与执行结果
• 官方 Quickstart
• 创建集成 API
• 固定版本的字段校验
• 会话请求类型
• 授权配置合并逻辑
• 前端 SDK
• Nango Webhooks：连接事件与验签
• 读取连接
• 连接读取权限
• 验签实现
• 版本协商
• Nango session 服务入口
• SDK 新旧入口说明
• Generic provider 配置
• Nango Proxy 源码：配置与 URL 拼接
• 代理头解析
• MCP Streamable HTTP：请求头、协议版本与响应流
• SDK 版本与包说明
• SDK HTTP 服务指南
• SDK 客户端连接指南
• MCP 授权规范
• Nango Generic 条件
• 工具搜索实现
• Pinned schema 实现
• 权限实现说明
• Generic 地址发现实现
• MCP 安全实践
• 代理重试实现
• 令牌刷新
• 删除连接接口
• Functions 开发流程
• Replit 案例
• 自维护说明
• 固定版本许可证
• Management MCP 的职责