metorial/metorial · 上手攻略

仓库：metorial/metorial
链接：https://github.com/metorial/metorial · 文档 https://metorial.com/api · 平台仓 https://github.com/metorial/metorial-platform
分类：AI Agent 基础设施 / MCP 集成目录
作者：spark
更新：2026-10-01

是什么

Metorial 是面向 AI Agent 的"身份与访问控制层"。它在 Agent 与外部 SaaS / 企业系统 / 数据源 / 自建 MCP 服务器之间插入一层统一的控制面，把 1200+ 集成以 OAuth、API key、服务账号等认证方式归一化，并配套 RBAC、SAML SSO、IAM、审计日志与可观测性。GitHub 主仓（metorial/metorial）本身是"集成目录 + SDK 示例"的展示入口，真正可自托管的引擎代码放在兄弟仓 metorial/metorial-platform。

⚠️ 涉及多个兄弟仓（metorial-platform / cli / lowerdeck / starbase / metorial-node / metorial-python），攻略正文聚焦主仓目录与 SDK 用法，自托管引擎另议。

解决什么问题

Agent 接生产系统时普遍存在三类痛点：①每个 SaaS 各写一套 OAuth / API key 流程，重复造轮子；②权限粒度散落在各集成里，CISO 看不到 Agent 拿了谁的 token 干了什么；③Claude Code / Codex / Cursor / Vercel AI SDK / LangChain / CrewAI 等不同客户端都要重新对接一遍。Metorial 的设计目标是把这些一次性收敛到一次调用 + 一个连接 URL。

⚠️ 用"控制面"切入 Agent 集成是 2026 年新趋势，与 Composio、Nango、Pipedream Connect 等同属"MCP 集成目录"赛道，但 Metorial 显式把"身份 + 权限 + 审计"放在首位，而非仅做工具清单。

快速安装

官方提供 TypeScript 与 Python 两套 SDK，路径都通过 npm / PyPI 安装。⚠️ 截至本攻略撰写，README 未给出确切的 latest 版本号，建议执行 npm view metorial version 与 pip index versions metorial 在安装前现场核实，避免被旧 lock 锁住。

TypeScript（Node 18+）：

mkdir metorial-quickstart && cd metorial-quickstart
npm init -y
npm install metorial @metorial/ai-sdk @ai-sdk/anthropic ai
export METORIAL_API_KEY=mk_xxx      # 自行到 metorial.com 申请

Python（3.10+）：

python -m venv .venv && source .venv/bin/activate
pip install metorial pydantic-ai python-dotenv
export METORIAL_API_KEY=mk_xxx

⚠️ 2026 年 npm 生态正处于 v12 升级与多次供应链蠕虫事件（如 5 月的 Mini Shai-Hulud、4 月的 Bitwarden 仿冒包）的高危窗口，建议固定 lockfile、开启 npm install --ignore-scripts 或在 CI 跑 aikido / socket 扫描后再发布。

核心用法

1) 零配置接入：Metorial Search

最简单的接入路径是内置的 metorial-search Provider——无需任何外部 OAuth 配置，可直接让模型调用网页搜索。

TypeScript（index.ts）：

import { Metorial } from 'metorial';
import { metorialAiSdk } from '@metorial/ai-sdk';
import { anthropic } from '@ai-sdk/anthropic';
import { stepCountIs, streamText } from 'ai';

const metorial = new Metorial({ apiKey: process.env.METORIAL_API_KEY! });

const deployment = await metorial.providerDeployments.create({
  name: 'Metorial Search',
  providerId: 'metorial-search',
});

const session = await metorial.connect({
  adapter: metorialAiSdk(),
  providers: [{ providerDeploymentId: deployment.id }],
});

const result = streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  prompt: '搜索 AI agent 领域最近一周的 3 条重要新闻并总结',
  stopWhen: stepCountIs(10),
  tools: session.tools(),
});

for await (const part of result.textStream) process.stdout.write(part);

Python（main.py）：

import asyncio, os
from metorial import Metorial
from metorial import metorial_pydantic_ai
from pydantic_ai import Agent

async def main():
    metorial = Metorial(api_key=os.environ["METORIAL_API_KEY"])
    deployment = metorial.provider_deployments.create(
        name="Metorial Search", provider_id="metorial-search",
    )
    session = await metorial.connect(
        adapter=metorial_pydantic_ai(),
        providers=[{"provider_deployment_id": deployment.id}],
    )
    agent = Agent(
        "anthropic:claude-sonnet-4-20250514",
        system_prompt="你是一个研究助理。",
        tools=session.tools(),
    )
    result = await agent.run("搜索 AI agent 领域最近一周的 3 条重要新闻并总结")
    print(result.output)

asyncio.run(main())

⚠️ claude-sonnet-4-20250514 来自 README 原文示例，不一定是 Anthropic 当前 production 模型，使用前请到 Anthropic 控制台确认模型 ID 是否仍可调用；如已下线请改用 claude-sonnet-4-5 或更新后的 ID。

2) 需要用户 OAuth 的服务（Slack / GitHub / Google Calendar / SAP）

走 setupSessions 三步流程：创建 setup session → 把 URL 抛给用户在浏览器里完成 OAuth → 拿回 authConfigId 再 connect。TypeScript 与 Python 用法对称，详见 metorial-node/examples/typescript-provider-config 与 metorial-python/examples/openai-agents。

3) 多 Provider 组合

一次 connect 里可以混合四种来源：dashboard 托管 deployment / 预创建 auth config / 内联凭据（access_token: 'ghp_...'）/ session template。这对多团队、多环境复用连接很关键。

4) 适配器矩阵

Metorial 提供 12+ 客户端适配，README 已列：AI SDK、OpenAI、Anthropic、Google Gemini、Mistral、DeepSeek、TogetherAI、LangChain、LangGraph、LlamaIndex、AutoGen、CrewAI、Google ADK、Haystack、OpenAI Agents。意味着同一份 provider 配置可在不同 Agent 框架间迁移。

典型适用场景

企业 Agent 接入内部系统：HR/CRM/工单系统需要走 SAML SSO + RBAC，Metorial 把"agent 用谁的账号访问"做成可审计单元，比散写在 LangChain tool 里的 OAuth code 强一个数量级。
多 Agent 框架试验：同一组 Slack / GitHub 集成同时给 Cursor / Claude Code / 自建 LangGraph agent 用，复用一份 auth config。
共享 MCP 服务器目录：自建 MCP 服务器登记到 Metorial 后，团队所有 Agent 都能从同一份元数据发现和调用，避免"每个项目重新写一遍 manifest"。

坑与注意

⚠️ METORIAL_API_KEY 不能进 git：README 没明说额度与计费，metorial.com 控制台才是唯一真相；和 OpenAI/Anthropic key 同样处理。
⚠️ OAuth callback URL 必须公网可达：本地开发时要么用 ngrok / Cloudflare Quick Tunnel，要么在 Metorial 控制台注册 http://localhost 重定向。
⚠️ 接入成本不是零：每个 Provider 仍要在 Metorial 平台注册并通过 OAuth，1200+ 集成不等于"开箱即用全部"，热门 SaaS 通常需要先做一次 setup。
⚠️ 主仓 ≠ 自托管引擎：想完全私有化要拉 metorial/metorial-platform 单独部署，主仓只是 catalog + 示例。
⚠️ claude-sonnet-4-20250514 等示例模型 ID：README 里的模型 ID 是写作时点的，生产前必须到对应 provider 控制台确认仍可用。
⚠️ npm 供应链高危期：2026 上半年已发生 Mini Shai-Hulud 蠕虫（5 月，跨 TanStack/UiPath/Mistral AI 100+ 包）等事件，安装 Metorial SDK 时建议固定版本号 + 跑 socket.dev / aikido 扫描。

与同类对比

维度	Metorial	Composio	Nango	Pipedream Connect
定位	身份 + 权限 + 工具三合一	工具目录 + OAuth	同步层 + 集成目录	工作流 + 集成目录
自托管	是（metorial-platform）	否（云为主）	部分	否
MCP 原生	是	部分	部分	弱
审计日志	一等公民	基础	基础	工作流日志
学习曲线	中（需先建 deployment）	低	中	中

⚠️ 对比表为 README 与公开资料整理的快速快照，未做基准实测。

一句话推荐结论

如果你要在生产里给 Agent 接多个 OAuth/SaaS、又要让 CISO 看到完整审计链，Metorial 是当前少有的把"身份 + 权限 + 工具"做成一等公民的开源控制面；纯做工具调用 demo 可以先从 metorial-search 入手跑通主流程，再决定是否上自托管引擎。