MCP在手、工具我有Treg接入MCP Server的零基础配置手册【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg一个 base URL、一个 token你的 Agent 就能调几千个外部 API 端点——这是 treg 作为OpenRouter for agent tools的承诺面向 AI Agent 的工具网关把 SEO、社媒、人企数据、广告、网页抓取、音视频生成等 3800 端点聚合成一份目录按次计费最低一分钱免去逐个供应商注册账号的苦役。而它最顺手的接入面就是 MCPModel Context Protocol无论宿主是 Claude Code、Cursor、ChatGPT 还是 opencode只要客户端说 MCPtreg 就能把自己变成一个可搜索、可调用、可计费的工具 Server。本文不重复官方文档而是带你对着源码把四件事讲透MCP 握手的真实形态、密钥怎么配才不踩坑、搜目录→看详情→发起调用的完整链路以及一份基于真实事故记录的配置错误预防清单。一、先理解握手treg 的 MCP 只有 HTTP 一种形态MCP 协议定义了两种传输stdio客户端拉起本地子进程通过标准输入输出通信与HTTP客户端连接一个远程 URL。stdio 适合把本地 CLI 包装成工具的进程内场景进程生命周期随客户端启停HTTP 则适合远程、多租户、可横向扩展的服务。treg 是后者而且只做后者。在 src/treg/mcp.py 的build_mcp_app里可以清楚看到这个选择transport server.streamable_http_app( streamable_http_path/, stateless_httpTrue, json_responseTrue, transport_securityTransportSecuritySettings( enable_dns_rebinding_protectionTrue, allowed_hosts_allowed_hosts(), allowed_origins_allowed_origins(resource_version), ), )三个关键词对应三句注释stateless_http是因为生产环境跑多个实例session 绑定传输需要 sticky routing无状态流式 HTTP 才可靠json_response是因为这些都是请求/响应式工具、没有流式内容跳过 SSE 分帧省下大部分延迟streamable_http_path/让传输直接挂在 mount 路径上。stdio 在这里没有任何位置——你不需要、也无法把 treg 装成本地子进程它就是那个远端 Server。真正的握手细节藏在RequireAuthForProtectedTools中间件里值得每个接入者知道它对每一个未带凭证的 JSON-RPC 请求包括initialize本身主动返回401WWW-Authenticate: Bearer resource_metadata…让客户端按 MCP 规范发现授权服务器并触发 OAuth 流程只有ping和notifications/*免凭证。也就是说没有 token 的客户端连握手都过不去而不是连上之后再一个个工具报错——这正是生产级 MCP ServerStripe、Subframe 一档的做法让客户端展示需要认证而不是已连接的假象。treg 同时提供两个公开表面配置时别混淆表面URL工具集团队面/mcp/https://treg.to/mcp/catalog_search、catalog_get、call、call_media、resources_list、balance、my_tools、catalog_request、feedback、review及 hub 工具Claude 目录面/mcp/v2/https://treg.to/mcp/v2/catalog_search、catalog_get、catalog_call_read、catalog_call_write、balance、catalog_requestV2 面只暴露经目录审核的 catalog 端点隐藏音视图生成平台并把调用拆成只读/写入两个工具好让 Claude 获得准确的安全信号见 README.md 的 Claude.ai connector 一节。二、密钥配置与模型选型的真相treg 的密钥只有一个treg 自己的 token不是任何供应商的 API key。供应商的凭证由 treg 服务端保管并在出站请求时注入密钥永不出服务器客户端从头到尾只持有一个 bearer。拿到 token 有四种方式权限语义不同treg login # 浏览器登录GitHub / Google / 邮箱验证码首登自动注册 treg login --email youcompany.com # 终端纯文本方式邮件 6 位码 treg login --token per-org-token # 非交互式适合 agents / CI treg org agent-new ci-bot # 为 Agent 铸造它自己的 per-org token可设 cap 与工具 ACL进程级身份走环境变量TREG_TOKEN可选TREG_ORG优先于~/.treg/config.json这样一台机器上的多个 Agent 可以各自持有自己的作用域见 src/treg/cli.py 的_client逻辑。注意一个坑treg login给的 bootstrap 临时 token七天有效不能写入 MCP 配置treg mcp install会明确拒绝——请使用团队 Default、Additional 或 Agent key。配置本身一句话搞定CLI 会自动探测并写入本机所有已安装的 Agenttreg mcp install它内部src/treg/mcp_install.py为不同 Agent 写不同格式Claude Code 走claude mcp add --scope user --transport httpCursor 与 opencode 写各自的 JSONCodex 写[mcp_servers.treg]表 内联http_headers。以 plugins/treg/mcp.json 为例手写配置的本质就是这样{ mcpServers: { treg: { url: https://treg.to/mcp/, headers: { Authorization: Bearer ${env:TREG_TOKEN} } } } }关于模型选型treg 不选模型也管不着模型。它是工具网关而非模型路由这正是它与 OpenRouter 的边界一个聚合非模型 API一个聚合模型 API。模型由你的 MCP 客户端决定treg 只通过instructions文本引导 Agent 的行为先 catalog_search 说你想做什么再看价格最后 call。但它确实按客户端区分能力_OpenAIClientGate根据 User-Agentopenai-mcp/、codex-mcp-client/对 OpenAI 系客户端隐藏review工具因为它把 agent 主动发起的评价当作行为数据采集。如果你在 ChatGPT/Codex 里看不到review那不是配置坏了是设计如此。三、从 MCP 客户端发起一次工具调用的完整链路以查一个域名的外链为例一次完整的 MCP 工具调用分三步第一步catalog_search——按想做的事而不是供应商名搜目录。它直接读进程内存中的catalog_store已解析约 1ms 返回verdict字段告诉你结果是strong这些端点能干活、closest接近需用catalog_get核实还是none目录没有用catalog_request提交需求指引下一个供应商的接入。第二步catalog_get——读单个端点的完整档案参数、确切价格、示例响应、实测成功率与样本数works/samples以及同能力其他供应商的对比。工具描述明确要求在调用前读它好告诉人类这单多少钱。第三步call——真正发起调用。参数形态齐全到能覆盖任何上游params承担 GET 的 query 或 POST 的 bodyquery/body显式槽位表达POST 同时带 query 和 body如 Bright Data 的?dataset_id 数组 bodyheaders传递 Google Ads 的login-customer-id这类按次 headeridempotency_key用于重试去重。布尔值按 HTTP 的 wire 格式序列化成true/false嵌套对象打成紧凑 JSON——str(True)那种 Python 写法会让上游直接 400。这步背后的工程值得展开_call_impl用httpx.ASGITransport在进程内把请求打到 treg 自己的/call/{endpoint_id}路由无 socket、无 DNS一次穿着 HTTP 外衣的函数调用。这么绕一圈不是浪费而是规则单点执行per-member 工具 ACL、deny rules、用户每日上限、平台每日上限、余额预留与结算全部只在/call/发生一次任何第二入口都可能让其中某条规则静默失效。目录内搜索可以直读内存但涉及钱、租户和凭证的一律回 API。调用按凭证阶梯自上而下服务团队自己注册的工具 → 团队存的密钥 → 无密钥的 verified public route免费→ 最后才是 treg 自己的共享 key按团队预付余额计费最低一分钱。返回里带着cost_usd由X-Treg-Cost-Micro换算、call_id、served_via当 treg 自有账户额度用尽、经 overflow relay 按真实价格代答时披露、replayed: true幂等重放未重复扣费。调用链的完整语义在 src/treg/mcp.py 的call工具与 docs/context/architecture/mcp-oauth.md 有逐字段说明。四、常见配置错误的预防清单以下是源码注释与真实事故记录中反复出现的坑按零基础最容易踩排序没带 bearer 就想握手RequireAuthForProtectedTools对无凭证请求一律 401客户端界面显示需要认证而非已连接。补上Authorization: Bearer token即可工具错误提示会明确指路Settings → copy token。把临时登录 token 装进 MCPtreg mcp install检测到 bootstrap scope 会拒绝写入用treg org agent-new name铸一个 per-org token 最干净——它自带团队归属消除这个人属于多个团队的歧义。多团队用户 token 未指定团队identity token 属于人可能同时在多个团队。_resolve_org会取 pinned/active 团队若都不明确就列出所有团队名让你问人类绝不静默挑一个去花余额。改用 per-org token 后这个问题消失OAuth grant 可在授权后treg mcp grantstreg mcp use-team改扣费团队无需重连。Codex 用bearer_token_env_var引用 token源码注释记录了一起真实事故——用户照文档配置后重启 Codex环境变量丢失treg 全部工具 401 被静默丢弃。必须用内联http_headerstreg mcp install就是这么写的。自托管没配 allowed hosts/originsSDK 的 DNS 重绑定防护默认空 allow-list会 421 拒绝一切请求。自托管需把部署域名加入TREG_MCP_ALLOWED_HOSTS/TREG_MCP_ALLOWED_ORIGINSsrc/treg/mcp.py 的_allowed_hosts/_allowed_origins。V2 面去掉尾斜杠/mcp/v2无斜杠会落到团队面 v1 mount拿到错误受众的 OAuth 元数据。NormalizeDirectoryMCPPath中间件已把两种拼写归一但手写.mcp.json时请带上斜杠。402 与 503 混淆402 团队预付余额不足响应体含balance_micro/estimated_cost_microMCP 路径会剥掉充值链接只留诊断503provider_capacity_unavailable treg 自有账号对该供应商额度用尽没扣你的钱换同能力供应商或用自己的 key 即可503provider_paused 部署暂停了该供应商保留连接别重连。幂等键用错同一 key 重放是没收到答案的重试不重复扣费返回replayed: true拿旧 key 发新请求会被拒绝重复搜索看变化是新工作必须换新 key。treg mcp install报 SSL/连接错误命令会先验证 token 再写入401 直接退出不写任何配置瞬时的 TLS 握手竞态会自动重试 1s/2s 退避。若持续失败先curl -I base_url排查网络别把坏 token 撒进所有 Agent 配置。把这条清单和前三节的握手、密钥、链路串起来你会发现 treg 的 MCP 接入其实只有三步拿一个 team token、配好TREG_TOKEN、treg mcp install或手写一段Authorizationheader。剩下的就是让 Agent 自己搜目录、看价格、发起调用了。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考