远程 MCP 服务器开发：3 个常见坑点总结

第一部分：导言

远程 MCP 服务器才刚刚开始腾飞。随着越来越多平台推出对模型上下文协议（MCP）的支持，我们看到开发者实验的快速增长——同样地，我们也看到许多常见的陷阱在首次构建 MCP 服务器的团队中出现。

在 Portia，我们测试了广泛的远程 MCP 服务器——从 Asana、Atlassian、Intercom 和 Stripe 等主要提供商，到 Fulcra、Globalping 和 Invideo 等新兴集成。在这个过程中，我们看到了一些反复出现的问题，这些问题使 MCP 服务器更难使用，更慢被采用，在生产环境中更加脆弱。

[快速背景说明 - Portia 是一个框架，能让开发者构建安全、可靠的 AI agent。我们很高兴能让你检查我们的 SDK 并给它一个 GitHub star！⭐ 🙏]

以下是我们建议每个 MCP 开发者避免的 3 个错误。

1. OAuth 重定向仅适用于 localhost

我们测试的多个 MCP 服务器在本地工作正常，但在真实的预发布或生产环境中出现问题。一个常见原因是：OAuth 重定向 URI 被硬编码为仅允许 localhost。虽然这在初期开发时可能很方便，但它阻止了在任何远程环境中的测试。

例如，我们无法集成 Atlassian，因为他们在授权流程中拒绝了有效的重定向 URI。这使得集成方几乎不可能在他们的部署流水线中正确测试你的服务器。

✅ 最佳实践：始终为 OAuth 客户端允许多个重定向 URI，包括本地和远程环境。理想情况下，应该让这个配置可以根据客户端进行自定义。

2. 缺少 .well-known OAuth 元数据或工具发现配置不当

MCP 规范依赖于能够使用 .well-known/oauth-authorization-server 端点自动发现 OAuth 配置。多个服务器——包括 PostHog、Semgrep 和 Invideo——要么没有提供这个文件，要么要求使用 token 来访问 tools/list 端点，这阻止了工具发现。

没有有效的 .well-known 文件：

• 客户端库无法自动配置 OAuth。
• MCP agent 无法轻松发现你的工具。
• 开发者体验受损。

✅ 最佳实践：确保你的 .well-known/oauth-authorization-server 是公开可访问的、符合标准的，并返回必要的 OAuth 元数据。

3. 服务器可用性不可靠

MCP 服务器需要处理动态发现、token 交换和工具调用——这要求相当高的可靠性水平。在我们的测试中，我们遇到了一些服务器停机维护（Asana）、间歇性不可用（Plaid、Neon）或授权流程失败并显示无用错误信息（Fulcra）的情况。

在 agent 时代，不可靠性不仅仅会阻止单个 API 调用——它可以破坏整个任务链和工作流。

✅ 最佳实践：尽早投资于正常运行时间监控、清晰的错误信息和全面的 OAuth 错误处理。MCP 服务器应该优雅地和可预测地失败。

好消息：使用 Portia 测试很简单

如果你正在构建新的远程 MCP 服务器，测试你的实现不必很痛苦。Portia 使得在你的 agent 应用程序中集成、验证和试验新的 MCP 服务器变得简单——通常只需 3 次点击。

随着 MCP 生态的成熟，我们很高兴能帮助开发者推出更可靠、对 agent 友好的集成——在预发布环境、生产环境和所有其他环境中都能正常工作。

关于 Portia 的更多信息

Portia AI 是一个开源框架，用于构建可预测、有状态、经过身份验证的 agent 工作流。

我们允许开发者对他们的多 agent 部署有尽可能多或尽可能少的监督，我们对生产就绪性有着近乎痴迷的关注。

我们邀请你试验我们的 SDK，打破东西，并在 Discord 上告诉我们你的进展情况。

如需采取进一步行动，你可以考虑屏蔽此人和/或举报滥用行为。