WeKnora 内置 MCP 服务管理指南系统级外部工具接入、数据库配置与安全保护机制【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora内置 MCP 服务是 WeKnora 中由系统管理员统一维护的系统级 MCPModel Context Protocol服务配置它向所有空间Tenant公开但敏感信息被隐藏、且不可编辑或删除。本文围绕该机制从管理视角讲解内置 MCP 服务的核心特性、数据模型与可见性规则并给出完整的 SQL 插入、验证、升级与移除操作步骤同时结合仓库源码说明其脱敏与保护逻辑的实现原理帮助开发者与运维人员在多空间环境中安全、一致地接入默认外部工具与资源。内置 MCP 服务是什么MCP 服务在 WeKnora 中对应mcp_services表它描述了外部工具/资源服务端点的连接方式传输类型、URL、认证、超时重试等。普通 MCP 服务按空间隔离、由各空间自行维护而内置 MCP 服务则是一个系统级别的配置形态其核心定位是为所有空间提供统一、默认的外部工具与资源接入确保任何空间无需单独配置即可使用同一套 MCP 服务。典型应用场景包括由运维统一接入一个 Web 搜索 MCP 服务所有空间直接可见可用统一提供代码解释器等工具型服务避免各空间重复填同一份认证信息以固定 ID 和只读属性保证配置一致性防止误改误删导致下游 Agent 行为漂移。内置 MCP 服务的四大特性特性说明所有空间可见内置 MCP 服务对所有空间都可见无需每个空间单独配置安全保护敏感信息URL、认证配置、Headers、环境变量在前端会被隐藏无法查看详情只读保护内置 MCP 服务不能被编辑或删除仅支持测试连接统一管理由系统管理员统一维护确保配置一致性和安全性从源码看这四条特性分别落在不同层次实现详见下文源码级解析其中所有空间可见由数据访问层完成安全保护由响应 DTO 完成只读保护由服务层完成。与内置模型的对比内置 MCP 服务与内置模型采用同一套is_builtin标识思想管理体验对齐特性内置模型内置 MCP 服务标识字段is_builtinis_builtin可见范围所有空间所有空间隐藏信息API Key、Base URLURL、认证配置、Headers、环境变量编辑保护不可编辑/删除不可编辑/删除前端标签显示内置标签显示内置标签启停控制—禁用开关始终启用两者的差异点在于内置 MCP 服务额外暴露了启用/禁用开关语义enabled字段默认开启作为只读展示而内置模型不提供该开关。可以推断这一设计使系统可以在不断言配置的前提下通过开关控制内置服务是否对外提供能力。源码级解析is_builtin如何工作数据模型在 internal/types/mcp.go 中MCPService定义了服务实体关键字段如下ID主键varchar(36)TenantID所属空间 ID与Name组成唯一索引idx_tenant_nameTransportType传输方式取值sse/http-streamable/stdioMCPTransportType常量定义于同文件 L18-L22URL服务地址SSE / HTTP Streamable 传输必填最长 512 字符Headers、AuthConfig、AdvancedConfig、StdioConfig、EnvVars均为 JSON 存储的配置块IsBuiltin bool是否内置服务GORM 默认falseL41注释明确写着visible to all workspaces。可见性数据访问层在 internal/application/repository/mcp_service.go 中所有查询都以tenant_id ? OR is_builtin true作为过滤条件GetByIDL29-L43Where(id ?, id).Where(tenant_id ? OR is_builtin true, tenantID)ListL47-L58Where(tenant_id ? OR is_builtin true, tenantID)ListEnabledL62-L73与ListByIDsL77-L95同理。这就是所有空间可见的底层实现任何空间查询 MCP 服务列表或按 ID 读取时内置服务都会随普通服务一起返回。敏感信息隐藏响应 DTO 层敏感信息隐藏发生在 internal/handler/dto/mcp.go 的NewMCPServiceResponseL83-L140中。该函数对内置服务执行全量剥离if svc.IsBuiltin { // Builtin services are shared across tenants — strip everything that // could leak how this tenant configured the underlying provider. resp.URL nil resp.Headers nil resp.EnvVars nil resp.StdioConfig nil resp.AuthConfig nil }也就是说内置服务的URL、认证配置、自定义 Headers、环境变量、stdio 配置一律不进入任何响应体。原因是内置服务跨空间共享同一行数据如果原样返回某个空间配置的上游服务地址与认证信息会对其他空间泄露敏感配置。与之配套的设计见同文件包注释与MCPAuthConfigResponseMCPServiceResponse在结构上就不包含api_key、token等秘密字段编译期不变量仅通过Credentials map[string]CredentialFieldMetadata暴露该字段是否已配置的布尔值L46而对内置服务Credentials字段整体省略注释说明they cant have per-tenant credentials。此外普通 MCP 服务的api_key/token在落库时还会经过 AES-256-GCM 加密MCPAuthConfig.Value()internal/types/mcp.go在配置了SYSTEM_AES_KEY时对APIKey与Token加密后再序列化Scan()L258-L282负责解密并处理密钥轮换导致的解密失败场景。这保证了数据库层面的原始数据也不是明文存储。只读保护服务层在 internal/application/service/mcp_service.go 中内置服务被明确拒绝三类变更更新L136-L139if existing.IsBuiltin { return fmt.Errorf(builtin MCP services cannot be updated) }删除L339-L340builtin MCP services cannot be deleted凭据修改L506-L507 与 L552-L553builtin MCP services cannot have credentials modified。对应的单元测试见 internal/application/service/mcp_service_test.go 与 L413-L417测试断言对内置服务执行更新/删除会返回包含 builtin 的错误。这一服务层拒绝与内置模型internal/application/service/model.go 中builtin models cannot be deleted的保护模式一致。只读保护之外的例外测试连接仅支持测试连接由 internal/handler/mcp_service.go 的TestMCPServiceL453-L484提供对应路由POST /mcp-services/{id}/test。该接口只读取服务配置并执行连通性/工具目录握手返回types.MCPTestResultSuccess、Message、Tools、Resources、OAuthRequired等字段见 internal/types/mcp.go不产生任何写操作因此对内置服务依然可用是管理员验证内置服务健康度的标准途径。支持的传输方式内置 MCP 服务支持两种传输方式对应MCPTransportType常量传输方式常量值适用场景Server-Sent Eventssse推荐用于流式体验HTTP Streamablehttp-streamable标准 HTTP 兼容注意出于安全考虑stdio传输方式在服务端已被禁用。MCPTransportStdio常量虽在 internal/types/mcp.go 中保留定义但创建internal/application/service/mcp_service.go、更新L148-L150、客户端建立连接internal/mcp/client.go与连接管理器internal/mcp/manager.go四处均统一拒绝错误信息为 stdio transport is disabled for security reasons; please use SSE or HTTP Streamable transport instead。如下图为 MCP 服务的连接配置编辑界面可见传输类型仅提供 SSE / HTTP Streamable 两个选项认证方式支持 Header、API Key/Token、OAuth 2.0 等与本文所述配置字段一一对应如何添加内置 MCP 服务内置 MCP 服务不能通过普通管理接口创建前端编辑入口面向普通服务需要直接向数据库插入is_builtin true的记录。步骤如下。1. 准备服务数据在插入前准备好以下配置信息字段是否必填说明name必填服务名称description选填服务描述transport_type必填sse或http-streamableurlSSE/HTTP Streamable 必填服务地址auth_config选填认证配置包括api_key、token等advanced_config选填超时、重试策略等高级配置tenant_id建议建议使用小于 10000 的空间 ID避免冲突headers选填自定义请求头HTTP Streamable 场景常用其中auth_config的结构对应 internal/types/mcp.go 的MCPAuthConfig支持auth_typeapi_key/bearer/oauth/ 空表示无认证、api_key_header默认X-API-Key、custom_headers、scopes、auth_server_metadata_url等。advanced_config对应MCPAdvancedConfigL115-L119包含timeout秒、retry_count、retry_delay秒默认值由GetDefaultAdvancedConfig()L346-L352给出timeout 30、retry_count 3、retry_delay 1。2. 执行 SQL 插入语句以下为两个完整示例分别演示 SSE 与 HTTP Streamable 传输方式-- 示例插入一个 SSE 传输方式的内置 MCP 服务 INSERT INTO mcp_services ( id, tenant_id, name, description, enabled, transport_type, url, auth_config, advanced_config, is_builtin ) VALUES ( builtin-mcp-001, -- 使用固定ID建议使用 builtin-mcp- 前缀 10000, -- 空间ID使用第一个空间 Web Search, -- 服务名称 内置 Web 搜索 MCP 服务, -- 描述 true, -- 启用状态 sse, -- 传输方式 https://mcp.example.com/sse, -- 服务地址 {api_key: your-api-key}::jsonb, -- 认证配置 {timeout: 30, retry_count: 3, retry_delay: 1}::jsonb, -- 高级配置 true -- 标记为内置服务 ) ON CONFLICT (id) DO NOTHING; -- 示例插入一个 HTTP Streamable 传输方式的内置 MCP 服务 INSERT INTO mcp_services ( id, tenant_id, name, description, enabled, transport_type, url, headers, auth_config, advanced_config, is_builtin ) VALUES ( builtin-mcp-002, 10000, Code Interpreter, 内置代码解释器 MCP 服务, true, http-streamable, https://mcp.example.com/stream, {X-Custom-Header: value}::jsonb, {token: your-bearer-token}::jsonb, {timeout: 60, retry_count: 2, retry_delay: 2}::jsonb, true ) ON CONFLICT (id) DO NOTHING;几点说明两条语句均使用ON CONFLICT (id) DO NOTHING保证幂等性重复执行不会报错若服务端配置了SYSTEM_AES_KEYauth_config中的明文密钥写入数据库后会被存储层的MCPAuthConfig.Value()自动加密为密文见前文敏感信息隐藏一节因此 SQL 里写入明文 API Key/Token 是可接受的写入形态PostgreSQL 使用::jsonb类型转换若使用 SQLite 等其他数据库请按对应方言将 JSON 字段作为文本/JSON 类型写入表定义见MCPService中各字段的gorm:type:json标注。3. 验证插入结果执行以下 SQL 查询验证内置 MCP 服务是否成功插入SELECT id, name, transport_type, enabled, is_builtin FROM mcp_services WHERE is_builtin true ORDER BY created_at;更贴近运维的验证方式是登录任意空间确认前端 MCP 服务列表中出现带内置标签的服务且详情中 URL、认证等字段不可见随后调用POST /mcp-services/{id}/test测试连通性。将现有 MCP 服务设置为内置服务如果你已经有一个 MCP 服务想将其设置为内置服务可以使用 UPDATE 语句UPDATE mcp_services SET is_builtin true WHERE id 服务ID AND name 服务名称;建议同时满足id与name两个条件避免误命中。升级为内置服务后该服务立即获得跨空间可见性与只读保护且其 URL、认证等敏感信息对所有空间的前端列表/详情响应不再可见。移除内置 MCP 服务如果需要移除内置标记恢复为普通 MCP 服务执行UPDATE mcp_services SET is_builtin false WHERE id 服务ID;注意移除内置标记后该 MCP 服务将恢复为普通服务可以被编辑和删除。恢复为普通服务后其归属空间tenant_id之外的其他空间将不再能看到它——因为可见性条件tenant_id ? OR is_builtin true中的is_builtin true已不再成立。因此该操作应视为将共享服务收归单个空间执行前需确认该服务原tenant_id归属的空间确实需要它。注意事项汇总ID 命名规范建议使用builtin-mcp-{序号}的格式例如builtin-mcp-001、builtin-mcp-002固定 ID 同时保证ON CONFLICT (id)幂等生效空间ID内置 MCP 服务可以属于任意空间但建议使用第一个空间 ID通常是 10000JSON 格式auth_config、advanced_config、headers等字段必须是有效的 JSON 格式幂等性使用ON CONFLICT (id) DO NOTHING确保重复执行不会报错安全性内置 MCP 服务的 URL、认证信息在前端会被自动隐藏但数据库中的原始数据仍然存在启用SYSTEM_AES_KEY时密钥字段为密文请妥善保管数据库访问权限传输方式限制仅支持sse和http-streamablestdio已被禁用创建、更新、客户端建立连接多处均拒绝凭据接口隔离对普通服务api_key/token等秘密字段通过独立的/credentials子资源维护主 PUT 接口不接收秘密字段internal/handler/mcp_service.go内置服务则完全不提供凭据修改能力SSRF 防护无论是通过接口创建还是更新 MCP 服务服务 URL 都会经过 SSRF 校验secutils.ValidateURLForSSRF与mcpsecurity.ValidateServiceOutboundURLs见 internal/handler/mcp_service.go。直接写库插入内置服务会绕过接口层的 SSRF 校验因此插入前务必人工确认目标地址是可信的外部服务端点。与其他模块的关系Agent 工具执行内置 MCP 服务同样出现在 Agent 的 MCP 工具目录中。MCPToolinternal/types/mcp.go支持require_approval开关配合 internal/agent/tools/mcp_tool.go 与审批 Gateapproval.Gate实现调用需审批的流控每个工具还可通过MCPToolApprovalinternal/types/mcp.go单独配置启用/禁用与审批策略。工具目录元数据服务响应中的Catalog字段tool_count、stale、synced_at来自 internal/application/service/mcp_metadata.go 的持久化目录摘要前端列表卡片据此展示服务规模与目录新鲜度。使用说明UsageInstructions字段为本地维护、不被目录刷新覆盖internal/types/mcp.go当其为空时EffectiveUsageInstructions()L49-L54回退到Description保证 Agent 总能获得服务用途上下文。小结内置 MCP 服务是 WeKnora 在多空间多租户架构下提供统一外部工具接入的管理机制通过is_builtin字段在数据访问层实现跨空间可见在 DTO 层剥离全部敏感传输细节在服务层拒绝编辑、删除与凭据变更仅保留测试连接能力。管理员只需按照本文的 SQL 流程插入带builtin-mcp-前缀、is_builtin true的记录即可让所有空间共享一套安全、只读、一致的默认 MCP 服务配合SYSTEM_AES_KEY加密与 SSRF 校验等既有安全设施可确保该机制在统一接入与敏感保护之间取得平衡。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考