企业官网建设流程全解析

mcp-brasil 是一个开源的MCP Server，把70 个巴西政府公开 API（IBGE、央行、国会、透明门户、司法系统、选举数据等，共 533 个工具）统一暴露给 AI 客户端。本指南带你完成三种部署方式：本地Docker 一键启动、Azure 云部署 + OAuth 2.0 企业鉴权、以及发布到Microsoft Teams的完整落地流程，新手照着做也能跑通。

🧭 先认识 mcp-brasil：一个 Server 覆盖 70 个数据源

mcp-brasil 的核心价值是"一处连接、处处可用"：无论你用的是 Claude Desktop、VS Code 还是云端 Agent，连上这一个 MCP 端点，就能用自然语言查询巴西的经济、立法、司法、选举、公共卫生等 15 个领域的官方数据。

它采用Auto-Registry 架构——每个数据源（feature）都是一个自包含的文件夹，由根 Server 自动发现并挂载，部署时不需要任何手动注册配置：

运行时的请求链路也非常直白：MCP 客户端发起 tool call → 内部 BM25 过滤器选出 top-10 相关工具 → HTTP 客户端调用政府 API → 格式化后返回：

💡 提示：66 个 API无需任何密钥即可使用，4 个使用免费密钥（1 分钟即可注册），开箱即用。

🐳 Docker 一键启动：3 步完成本地部署

mcp-brasil 自带生产级 Dockerfile（基于 Python 3.13 + uv，镜像层做了依赖缓存优化），以及 docker-compose.yml。

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/mc/mcp-brasil cd mcp-brasil

第 2 步：（可选）准备.env

compose 文件会自动加载.env。最小化部署只需要留一个空文件，或者按需填入 API 密钥：

# .env 示例（全部可留空，核心 API 无需密钥） TRANSPARENCIA_API_KEY= DATAJUD_API_KEY=

第 3 步：启动并验证

docker compose up -d

启动后 compose 里内置的健康检查会每 30 秒访问一次/health端点。手动验证：

curl http://localhost:8061/health # {"status":"healthy"}

此时 MCP 端点位于http://localhost:8061/mcp，可以在 Quick Start 中找到将它接入 Claude Desktop / VS Code / Claude Code 的配置片段。

📦 附赠：数据集自动预热（Warmup）

容器入口脚本 docker-entrypoint.sh 有一个巧妙设计：启动前会检查MCP_BRASIL_DATASETS环境变量——如果配置了大数据集（如 TSE 选举数据、SIAPA 不动产数据），会自动运行 scripts/warmup_datasets.py 预先下载并导入 DuckDB 缓存，之后再启动 Server。这样用户的第一次查询就不会卡在几分钟的下载上：

# .env 中启用数据集预热 MCP_BRASIL_DATASETS=spu_siapa,tse_candidatos,tse_bens

即使预热失败，入口脚本也会降级继续启动 Server（数据集改为按需懒加载），不会导致容器崩溃。

⚙️ 部署核心配置速查表

所有行为都由环境变量驱动（定义见 src/mcp_brasil/settings.py）。部署时最常用的几项：

完整变量清单可查阅官方配置文档。

☁️ Azure 云部署：从零搭建 Container Apps

要对接 OAuth 和 Teams，需要一个公网可达的 HTTPS 端点。Azure Container Apps 是官方文档（docs/deploy/foundry-teams.md）推荐方案，按顺序执行 5 步（需已安装并登录 Azure CLI）：

1. 创建资源组：az group create --name rg-mcp-brasil --location eastus2

2. 创建容器镜像仓库 ACR并远程构建镜像（无需本地 Docker）：az acr build -r <ACR> -t mcp-brasil:latest -f Dockerfile .

3. 创建 Container App，关键环境变量如下：

   环境变量	值
   MCP_BRASIL_AUTH_MODE	multi（同时接受 OAuth + 静态 Token）
   MCP_BRASIL_API_TOKEN	随机生成的 Token（后续给 Teams Agent 用）
   MCP_BRASIL_BASE_URL	Container App 的公网 FQDN
   MCP_BRASIL_OAUTH_PROVIDER	azure

   其中AUTH_MODE=multi是企业场景的最佳实践：一个端点同时服务 Claude.ai 的 OAuth 用户和 Foundry 的 Token 调用，互不冲突。

4. 获取公网 URL：https://<fqdn>/mcp就是你的 MCP Server 地址（下称$BASE_URL）

5. 验证部署：带 Token 请求initialize方法应返回 200

💰 成本参考：开发环境总计约R$ 30-50/月（消费型 Container App 按用量计费 + 存储）。详见 docs/deploy/azure-datasets.md。

🔎 需要持久化大数据集？挂载 Azure Files

如果MCP_BRASIL_DATASETS里挂了tse_votacao（1.6GB）这类数据集，建议挂载 Azure Files 共享卷到/cache/mcp-brasil，让 DuckDB 缓存在重启和扩缩容之间持久化。docs/deploy/azure-datasets.md 里有完整的 CLI 命令和避坑指南（比如 Consumption 计划 8GB 内存上限下，建议只把小数据集放进自动预热，大集改为懒加载）。

🔐 OAuth 企业级鉴权：Azure Entra ID 五步配置

想让Claude.ai Web 端的 Connector 接入 mcp-brasil？它的 Connector UI 只认 OAuth（不接受静态 Bearer Token），因此需要注册一个 Azure Entra ID 应用。完整步骤在 docs/deploy/azure-oauth.md，这里给出关键五步：

1. 注册应用：Microsoft Entra ID → App registrations → New registration，Redirect URI 填Web平台的{BASE_URL}/auth/callback（必须精确匹配，含https://，无末尾斜杠）
2. 暴露 API scope：Expose an API 中添加名为read的 scope（状态 Enabled）
3. 修改 Manifest：将requestedAccessTokenVersion改为2——这是最容易漏的一步，否则签发的 v1.0 Token 会被 FastMCP 拒绝
4. 创建 Client Secret：Certificates & secrets 中生成并立即复制（只显示一次）
5. 写入容器：用az containerapp secret set把三个凭据存为 secrets，再通过secretref:引用设置环境变量，切勿明文写在--set-env-vars中：

az containerapp update -n mcp-brasil -g rg-mcp-brasil \ --set-env-vars \ MCP_BRASIL_AUTH_MODE=oauth \ MCP_BRASIL_OAUTH_PROVIDER=azure \ MCP_BRASIL_BASE_URL=$BASE_URL \ AZURE_REQUIRED_SCOPES=read \ AZURE_CLIENT_ID=secretref:azure-client-id \ AZURE_CLIENT_SECRET=secretref:azure-client-secret \ AZURE_TENANT_ID=secretref:azure-tenant-id

✅ 部署验证三连

# 1. OAuth 发现端点应返回 JSON 元数据 curl -sS $BASE_URL/.well-known/oauth-protected-resource | jq # 2. 无 Token 请求应返回 401 + www-authenticate 头 curl -sS -i -X POST $BASE_URL/mcp -d '{"jsonrpc":"2.0","method":"initialize","id":1}' # 3. 容器日志确认 provider az containerapp logs show -n mcp-brasil -g rg-mcp-brasil --tail 30 | grep -i auth # -> "Auth enabled: AzureProvider (Entra ID)"

验证通过后，在 Claude.ai 的 Settings → Connectors 中添加自定义连接器，URL 填{BASE_URL}/mcp，ID/Secret 留空即可（FastMCP 通过动态客户端注册 DCR 自动完成授权流），用户将重定向到 Microsoft 登录页完成鉴权。

💬 Microsoft Teams 落地：Azure AI Foundry 四步发布

最后把能力送到团队每天工作的地方。Foundry Agent Service 通过MCPTool（key-based Bearer Token）连接 mcp-brasil——这正是前面AUTH_MODE=multi的意义所在。步骤参照 docs/deploy/foundry-teams.md：

第 1 步：添加 MCP 工具在 Foundry Portal（需开启新版界面）→ 项目 → Tools → 添加 Custom → MCP，认证方式选Baseado em chave（基于密钥），值填Bearer <MCP_BRASIL_API_TOKEN>。

⚠️ 不要选 OAuth Identity Passthrough——它与 FastMCP 的 DCR 不兼容，会报 "Client Not Registered"。

第 2 步：创建 Agent仓库自带 scripts/foundry_agent.py 脚本一键创建：

uv sync --group foundry python scripts/foundry_agent.py create # Output: Agent created: name=agente-brasil, version=1

System prompt 建议要求 Agent：始终用巴西葡语回答、标注数据来源、复杂查询先用planejar_consulta规划、多查询用executar_lote并行执行。

第 3 步：Playground 测试试试这些问题："当前 Selic 利率是多少？"、"按人口排列巴西 10 大城市"、"本周议院投票通过了哪些法案？"

第 4 步：发布到 TeamsPlayground 右上角Publish→ 选 Microsoft Teams，填写应用名和描述。随后需要 M365 管理员在 Admin Center → Integrated apps 中审批该应用，约 1-2 小时传播后，团队成员就能在 Teams 搜索栏找到 Agent 直接对话。

🛠️ 部署故障排查：4 个高频问题

想快速回滚到纯静态 Token 模式？只需az containerapp update ... --set-env-vars MCP_BRASIL_AUTH_MODE=static MCP_BRASIL_API_TOKEN=<token>，无需重新构建镜像。

📚 总结与延伸阅读

至此你已经完成了 mcp-brasil 的全链路部署：Docker 本地 → Azure 云端 → OAuth 企业鉴权 → Teams 团队助手。几个关键决策再回顾一下：

• 本地/个人使用 →docker compose up -d，零配置
• 需要 OAuth（Claude.ai Connector）→AUTH_MODE=oauth+ Entra ID 应用
• 同时服务 OAuth 和 Foundry/Teams →AUTH_MODE=multi（推荐企业方案）

延伸阅读：

• Quick Start 快速入门
• 部署文档目录：Azure OAuth · Azure 数据集缓存 · Teams 落地
• 配置参考 · 数据来源清单 · 可接受使用政策

⚠️ 免责说明：mcp-brasil 是社区独立项目，数据均来自巴西政府官方 API，但 AI 模型的解读可能存在偏差——用于决策、新闻或司法用途前，请务必核对官方来源。