集成连接 MCP 服务器(含 OAuth 授权)
连接 MCP 服务器(含 OAuth 授权)
在集成里加一个 MCP 服务器,Func 里用 ctx.mcp 调它的工具。支持需要 OAuth 登录的服务器,可以用站长的账号,也可以让每个访客连接自己的账号。token 由平台保管,不进 Func。
在集成里加一个 MCP 服务器之后,Func 里用 ctx.mcp('名称', 工具, 参数) 就能调它的工具,包括需要登录授权(OAuth)的服务器,比如 Linear、Notion、Sentry。授权流程和 token 都由平台处理,代码里拿不到 token。
添加 MCP 服务器
打开编辑器的后端 → 集成,点 MCP,按下表填写。保存时平台会真的连一次服务器,地址或认证方式不对当场报错。
| 字段 | 填什么 | 必填 |
|---|---|---|
| 名称 | 代码里的服务器名,比如 linear。只能用字母、数字、- 和 _,不能叫 creght | 是 |
| 服务器地址 | MCP 的 Streamable HTTP 地址,一般以 /mcp 结尾,比如 https://mcp.linear.app/mcp。只支持 https | 是 |
| 认证方式 | OAuth:需要登录授权的服务器(默认)。Token:服务器给了一个固定 token。无:公开服务器 | 是 |
| 用谁的账号 | OAuth 时选择:我的,或每个访客连接自己的 | OAuth 时 |
| Scope | 留空则按服务器的要求申请 | 否 |
| OAuth 客户端 ID / 密钥 | 只有服务器不支持自动注册客户端时才需要。大多数服务器(Linear、Notion、Sentry、Atlassian)都支持,不用填 | 否 |
选「我的」时,保存后在卡片上点授权,弹窗里登录并同意即可。卡片上可以看到授权状态和服务器提供的全部工具。
在 Func 里调用
export async function createTask(input, ctx) {
const tools = await ctx.mcp.tools('linear') // [{ name, description, input_schema }]
const issue = await ctx.mcp('linear', 'create_issue', {
title: input.title,
team: 'ENG',
})
return issue
}
| 方法 | 说明 |
|---|---|
ctx.mcp(name, tool, args?) | 调一个工具。返回工具的结构化结果;工具只返回文本时,是 JSON 就解析,不是就原样返回。工具报错会抛异常 |
ctx.mcp.tools(name) | 列出工具:name、description、input_schema。写代码前先看一次,工具名和参数以它为准 |
ctx.mcp.status(name) | 当前能不能调:connected、connect_as、signed_in、authorize_url |
ctx.mcp.disconnect(name) | 删除当前访客自己的授权。只对「每个访客连接自己的」生效 |
每个访客连接自己的账号
平台不提供访客端的界面,按钮和提示由网站自己的页面来做。平台提供的是一个授权入口:
/auth/mcp/start?server=linear&redirect=/dashboard
访客必须已经登录网站。打开这个地址后,平台带访客去服务器那边登录并同意,完成后跳回 redirect 指定的站内页面,地址上带 ?mcp_connected=linear;失败时带 ?mcp_error=原因。以后这个访客的调用会自动用他自己的账号。
推荐把「需要连接」当作正常的返回值,而不是让页面去处理异常:
import type { TalizenFuncContext } from 'talizen/func-runtime'
export async function myIssues(input: unknown, ctx: TalizenFuncContext) {
ctx.auth.requireUser()
const st = await ctx.mcp.status('linear')
if (!st.connected) return { needConnect: true, url: st.authorize_url }
try {
const issues = await ctx.mcp('linear', 'list_issues', { assignee: 'me' })
return { needConnect: false, issues }
} catch (e: any) {
if (e.code === 'mcp_authorization_required') {
return { needConnect: true, url: st.authorize_url }
}
throw e
}
}
export async function disconnect(input: unknown, ctx: TalizenFuncContext) {
ctx.auth.requireUser()
return ctx.mcp.disconnect('linear')
}
页面里:
import { invoke } from 'talizen/func'
const res = await invoke('linear.myIssues', {})
if (res.needConnect) {
const href = res.url + '&redirect=' + encodeURIComponent(location.pathname)
// render <a href={href}>Connect Linear</a>
}
访客身份优先使用网站的登录用户(ctx.auth),没有时使用项目成员登录(ctx.member)。所以在编辑器里试跑 Func 时,用的是你在集成卡片上点「连接我的账号」授权的那一份。
安全与限制
- token 只保存在平台,加密存储,不会进入 Func。快过期时平台会自动刷新;刷新也失败时,调用返回
mcp_authorization_required。 - 不要在 Func 里自己实现 MCP 的授权,也不要用
fetch直接调 MCP 服务器。只有选了 Token 认证时,才可以打开「暴露给 Func」用环境变量自己调。 - 只支持 Streamable HTTP,不支持旧的 HTTP + SSE 传输和本机的 stdio 服务器。
- 每次调用会新建一次连接,比调普通接口多一次往返,不适合在一个请求里调几十次。
- 修改服务器地址、认证方式、授权身份或客户端 ID 后,已有的授权全部失效,需要重新授权。
