将现有API作为MCP服务器公开

此存储库提供了关于在不同平台和工具上将现有API作为模型上下文协议（MCP）服务器公开的全面文档。MCP服务器使AI助手能够通过标准化协议安全地与您的API交互。

快速入门指南

根据您现有的基础设施选择您的平台：

平台	先决条件	设置时间
邮递员	Node.js 18+	10分钟
谷歌云（Apigee）	GCP项目，Apigee X	30分钟
微软 Azure	Azure APIM实例	20分钟
亚马逊云服务	使用Bedrock AgentCore、AWS CLI的AWS帐户	20分钟

术语表

MCP（模型上下文协议）：AI助手与外部工具和API交互的标准化协议
MCP服务器：一种将API作为AI助手可以发现和调用的工具公开的服务
MCP客户端：连接到MCP服务器的应用程序（如Claude Desktop或GitHub Copilot）
标准：本地MCP服务器的标准输入/输出通信方法
SSE（服务器发送事件）：用于远程MCP服务器的基于HTTP的流协议
SigV4：AWS签名版本4，AWS服务的身份验证协议
工具：通过MCP公开的API操作，人工智能助手可以调用

邮递员

Postman提供了一个MCP生成器，允许您从Postman API网络中可用的公共API创建MCP服务器。

先决条件

已安装Node.js 18或更高版本
可访问API网络的邮差帐户
对REST API的基本理解

生成MCP服务器

在“邮差”标题中，单击 API网络
在左侧边栏中，单击 MCP发生器
从Postman API网络搜索公共API
从搜索结果中选择公共工作区
浏览工作区的集合（相关API请求组）和文件夹
选择要添加到MCP服务器的特定API请求
点击 添加请求
（可选）搜索并添加来自其他公共工作区的请求，以组合多个API
点击生成创建MCP服务器包
点击 下载ZIP 并按照屏幕上的指示操作

设置您的MCP服务器

将下载的文件解压缩到所需的位置
打开终端并导航到MCP服务器的根目录：

   cd /path/to/your-mcp-server

安装依赖项：

   npm install

列出用于验证设置的可用工具：

   npm run list-tools

此命令列出了工具的信息，包括它们的文件名。您可以在 tools/ 目录。 5.如果您的API需要身份验证，请将敏感数据（如API密钥或令牌）存储在 .env 文件：

   API_KEY=your_api_key_here
   API_SECRET=your_api_secret_here

请参考您的项目 README.md 特定配置要求的文件。

启动MCP服务器

从标准输入/输出开始（用于Claude Desktop的本地使用）：

node mcpServer.js

从流式HTTP（用于远程访问）开始：

node mcpServer.js --streamable-http

使用以下命令停止服务器 Control+C （Mac）或 Ctrl+C （Windows/Linux）。

配置MCP客户端

要将Postman MCP服务器与Claude Desktop一起使用，您需要将其添加到Claude的配置文件中。

配置文件位置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

配置步骤：

找到并打开 claude_desktop_config.json 文本编辑器中的文件
添加您的Postman MCP服务器配置：

{
  "mcpServers": {
    "postman-api": {
      "command": "node",
      "args": ["/absolute/path/to/your/mcpServer.js"]
    }
  }
}

替换 /absolute/path/to/your/mcpServer.js 带有MCP服务器文件的完整路径

- 示例（macOS/Linux）： "/Users/username/postman-mcp-server/mcpServer.js" - 示例（Windows）： "C:\\Users\\username\\postman-mcp-server\\mcpServer.js"

保存配置文件

完全重新启动Claude Desktop（退出并重新打开应用程序）

在Claude Desktop中打开新对话

您的Postman API工具现在应该可供Claude使用

注：当Claude Desktop启动时，MCP服务器会自动运行。您不需要手动启动它 node mcpServer.js 当与Claude Desktop一起使用时。

故障排除

问题：“找不到模块”错误

解决方案：确保你跑了 npm install 在MCP服务器目录中

问题：API请求失败，401未授权

解决方案：验证API密钥是否在中正确设置 .env 在工具文件中正确配置了文件和身份验证标头

问题：工具未出现在Claude Desktop中

解决方案：修改配置文件后重新启动Claude Desktop，并检查路径 mcpServer.js 是绝对的

______________________________________________________________________

谷歌云平台（Apigee）

Apigee现在提供 原生MCP支持 它允许企业将现有的API转换为安全、受管理的MCP工具，而无需编写代码或部署单独的MCP服务器。

原生MCP支持（预览版） Apigee的原生MCP支持目前处于预览。使用此功能，您不需要对现有的API进行任何更改，编写任何代码，或部署和管理任何本地或远程MCP服务器。Apigee使用您现有的API规范并管理底层基础设施和代码转换。 要访问此功能，请联系您的Apigee或Google Cloud帐户团队。

主要特点

无需更改代码：使用OpenAPI规范将现有API转换为MCP工具
完全管理的基础设施：Apigee处理MCP服务器、转码和协议处理
企业级安全：将Apigee的30多种内置授权、身份验证和治理策略扩展到AI代理
API集线器自动注册：部署的MCP代理自动在Apigee API集线器中注册
综合可观测性：使用Apigee Analytics和API Insights监控MCP工具的使用情况
框架兼容性：适用于ADK、LangGraph和其他流行的代理框架

主要优势

无额外操作负担：您不需要为每个API设置和管理MCP服务器。只需部署一个MCP代理，Apigee就会负责其余的工作——全面管理MCP服务器、转码和协议处理。

工具可观察性和治理Apigee内置的身份、授权和安全策略可以保护和管理您的MCP端点和工具。使用Apigee Analytics监控MCP客户端的工具使用情况。

全面的工具安全：Apigee确保所有代理交互都是安全的：

- 使用云数据丢失防护（DLP）对敏感数据进行分类和保护 - 使用模型装甲防范迅速注射和越狱企图 - 为代理和用户调用MCP工具强制执行适当的IAM权限 - 使用 Apigee高级API安全为了提供额外的保护

集中工具目录：部署的MCP代理会自动在Apigee API中心注册您的规范，使您能够维护可搜索的集中式工具目录并促进工具的重复使用。

工作原理（原生MCP支持）

创建MCP代理：在Apigee环境组中，使用以下命令创建MCP代理：

- 基础路径： /mcp - 目标URL: mcp.apigeex.com - 包括您的OpenAPI规范

自动生成刀具：当a tools/list 或 tools/call 当向MCP端点发出请求时，Apigee使用OpenAPI规范中记录的操作作为MCP工具列表。

应用策略：将MCP代理捆绑在一个 API产品并应用精细的配额、身份和访问策略，以确保只有授权的MCP客户端、代理和开发人员才能列出和调用这些工具。

监视器使用情况：使用Apigee Analytics监控MCP工具的使用情况，并使用Apagee API集线器中的“Insights”选项卡查看MCP端点的流量和性能指标。

代理开发工具包（ADK）集成

开发者使用代理开发工具包（ADK）在谷歌生态系统中构建代理时具有精简的优势：

ADK工具集：ADK包括一个 Apigee和应用程序集成工具集，使将自定义代理连接到MCP端点变得容易
ApigeeLLM包装材料：使用 ADK的ApigeeLLM包装通过Apigee代理公开LLM端点，将治理集成到代理工作流中
部署选项：使用顶点AI代理引擎使用以下命令部署代理并在整个组织中实施代理双子星企业版

备注：ApigeLLM包装器目前设计用于Google AI Studio中的Vertex AI和Gemini API，并计划支持其他模型和接口。

______________________________________________________________________

替代方案：基于样本的方法

如果您需要立即可用的解决方案或希望对MCP服务器实现进行更多控制，可以使用 Apigee MCP样品来自谷歌云平台。此示例提供了一个MCP服务器实现，该实现可动态发现Apigee管理的API产品并将其公开为MCP工具。

先决条件（基于样本）

Apigee X至少有一个环境的组织
启用了以下API的GCP项目：

- Vertex AI API - 云运行API - 阿皮吉API

在同一GCP项目中启用和提供Apigee API集线器
gcloud CLI已安装并配置
已安装Docker（用于构建容器映像）
已安装apigeecli(下载版本)
jq（JSON处理器）已安装(下载)

入门（基于示例）

1.克隆存储库：

git clone https://github.com/GoogleCloudPlatform/apigee-samples.git
cd apigee-samples/apigee-mcp

2.配置环境变量：

编辑 apigee-mcp/env.sh 并根据您的Apigee和GCP项目详细信息设置以下变量：

export PROJECT="
"                    # Your GCP Project ID
export REGION=""                         # e.g., us-central1
export APIGEE_ENV=""                 # e.g., eval
export APIGEE_HOST=""               # e.g., your-org-eval.apigee.net
export SA_EMAIL=""                     # e.g., apigee-runtime-sa@
.iam.gserviceaccount.com

配置示例：

export PROJECT="my-gcp-project"
export REGION="us-central1"
export APIGEE_ENV="eval"
export APIGEE_HOST="my-org-eval.apigee.net"
export SA_EMAIL="apigee-runtime-sa@my-gcp-project.iam.gserviceaccount.com"

3.获取环境文件：

source ./env.sh

4.部署：

./deploy-all.sh

部署脚本执行以下操作：

为存根服务和MCP服务器构建容器映像
将服务部署到Google Cloud Run
配置Apigee工件（API代理、产品、开发人员应用程序）
设置Apigee API集线器条目
输出MCP服务器端点URL

有关详细的设置说明，请参阅存储库中的README.

附加资源

故障排除

问题：“获取API产品失败”

解决方案：验证 MCP_BASE_URL 指向有效的Apigee API集线器终结点，并且凭据正确

问题：容器无法启动（基于示例的方法）

解决方案：使用以下命令检查云运行日志 gcloud run services logs read mcp-server 并验证是否设置了所有必需的环境变量

问题：OAuth身份验证失败

解决方案：确保Apigee中的开发者应用程序具有正确的凭据，并且API产品与之关联

问题：代理未显示MCP工具

解决方案：验证您的OpenAPI规范是否有效，操作是否正确记录

问题：调用MCP工具时拒绝访问

解决方案：检查API产品是否包括MCP代理，以及客户端是否具有正确的凭据

有关更多故障排除帮助，请参阅存储库的故障排除部分

______________________________________________________________________

微软 Azure

Azure API管理允许您使用其内置的AI网关功能将REST API公开为远程MCP服务器。

先决条件

支持AI网关的Azure API管理实例。

- 推荐等级: Basic v2, Standard v2，或 Premium v2 本机包含AI网关功能。 - 经典级别: Basic, Standard，以及 Premium 需要加入AI网关早期访问计划。 - > 如果需要创建新实例，请按照以下步骤操作官方Azure文档并选择一个 v2 用于立即访问AI网关的层。

在API管理中管理的HTTP-兼容REST API
带有GitHub Copilot扩展的Visual Studio代码（用于测试）
具有适当权限的Azure订阅

加入AI Gateway早期访问

对于经典级别（基本、标准、高级），您必须加入AI网关早期访问组：

导航到Azure门户中的API管理实例
首选设置 > 特性
找到 AI网关 然后单击 加入早期访问
等待最多2小时以应用更新
通过检查以下内容进行验证 MCP服务器 出现在API下的左侧菜单中

重要配置说明

严重： 如果通过Application Insights或Azure Monitor在全局范围（所有API）启用诊断日志记录，则必须将前端响应的“要记录的有效负载字节数”设置为0。

原因：响应体日志会触发缓冲，这会干扰MCP服务器的流行为，并可能导致工具调用失败。

要配置：

引导到 应用程序编程接口 > 所有API > 设置
在...之下 诊断日志，查找 前端响应
集 要记录的有效负载字节数 到 0
点击保存

公开API作为MCP服务器

在Azure门户中，导航到您的API管理实例
在左侧菜单中 应用程序编程接口，选择 MCP服务器 > +创建MCP服务器
选择 “将API公开为MCP服务器”
在 后端MCP服务器:

- 从下拉列表中选择要公开的托管API - 选择一个或多个要公开为工具的API操作（或全部选择）

在 新建MCP服务器:

- 输入a 名字对于MCP服务器（例如。， customer-api-mcp) - （可选）输入描述解释服务器提供什么

点击创建

MCP服务器已创建并列在 MCP服务器 刀片及其服务器URL端点的格式如下：

https://[your-apim-instance].azure-api.net/mcp/[server-name]

配置策略

配置API管理策略以管理MCP服务器。这些策略适用于作为工具公开的所有API操作。

重要提示： 请勿使用访问响应正文 context.Response.Body 在MCP服务器策略中，这会触发响应缓冲并干扰流行为。

要配置策略，请执行以下操作：

引导到 应用程序编程接口 > MCP服务器
选择您的MCP服务器
点击政策在工具栏中
编辑策略XML

示例：IP速率限制

示例：添加身份验证标头


    
        
        
            Bearer {{api-key-secret}}

在Visual Studio代码中添加MCP服务器

打开安装了GitHub Copilot的Visual Studio代码
使用 “MCP:添加服务器” 命令面板中的命令（Ctrl+Shift+P或Cmd+Shift+P）
选择服务器类型： HTTP（HTTP或服务器发送事件）
输入API管理中的服务器URL：

   https://your-apim.azure-api.net/mcp/your-server-name

输入您选择的服务器ID（例如。， azure-customer-api)
选择保存位置：

- 工作区设置: .vscode/mcp.json （项目特定） - 用户设置：全球 settings.json （适用于所有项目）

将身份验证配置添加到JSON文件：

使用订阅密钥：

{
  "mcp": {
    "servers": {
      "azure-customer-api": {
        "url": "https://your-apim.azure-api.net/mcp/your-server-name",
        "headers": {
          "Ocp-Apim-Subscription-Key": "your-subscription-key"
        }
      }
    }
  }
}

使用OAuth令牌：

{
  "mcp": {
    "servers": {
      "azure-customer-api": {
        "url": "https://your-apim.azure-api.net/mcp/your-server-name",
        "headers": {
          "Authorization": "Bearer your-oauth-token"
        }
      }
    }
  }
}

在代理模式下使用工具

在GitHub Copilot聊天中，选择 代理模式 （单击代理图标）
点击工具按钮，查看连接的MCP服务器中的可用工具
从MCP服务器中选择一个或多个工具
输入提示以调用该工具（例如，“获取ID 12345的客户详细信息”）
选择继续查看API的结果

故障排除

问题：401未经授权的错误

解决方案：使用添加身份验证 set-header 手动附加授权令牌的策略
验证订阅密钥或OAuth令牌是否有效，并且可以访问API
检查策略是否应用于正确的范围（MCP服务器或API级别）

问题：API调用在API管理测试控制台中工作，但在代理中失败

解决方案：验证MCP服务器的安全策略是否配置正确
检查CORS策略是否允许来自MCP客户端的请求
确保端点URL正确，并且可以从客户端访问

问题：启用诊断日志时，MCP服务器流式传输失败

解决方案：在 所有API 范围
引导到 应用程序编程接口 > 所有API > 设置 > 诊断日志
集 要记录的有效负载字节数 前端响应 0

问题：工具未出现在VS代码中

解决方案：添加MCP服务器配置后重新启动VS代码
通过在浏览器中测试验证MCP服务器URL是否可访问
检查GitHub Copilot扩展是否为最新版本

问题：“无法连接到MCP服务器”

解决方案：验证Azure API管理实例是否位于受支持的层中
检查从您的计算机到APIM端点的网络连接
确保没有防火墙或代理阻止连接

______________________________________________________________________

亚马逊云服务

亚马逊基岩代理核心网关提供 原生MCP支持 它允许企业通过一个完全托管的网关将其现有的API、Lambda函数和其他后端服务转换为安全、受管理的MCP工具，而无需部署单独的MCP服务器。

原生MCP支持 Amazon Bedrock AgentCore Gateway为您的AI代理提供了一个完全管理的“工具前门”。它将多个后端系统（包括REST API、AWS Lambda函数、Smithy模型和现有的MCP服务器）聚合到一个统一的MCP兼容端点中。您不需要编写MCP协议代码或管理MCP服务器基础设施。

主要特点

无需MCP服务器代码：使用现有的API规范将现有的RESTAPI、Lambda函数和Smithy模型转换为MCP工具
完全管理的基础设施：AgentCore网关处理MCP服务器、协议转码、工具发现和路由
多种目标类型：支持Lambda函数、OpenAPI模式、Smithy模型、原生MCP服务器和内置集成模板（Salesforce、Slack、Jira、Asana、Zendesk）
企业级安全：具有入站（代理到网关）和出站（网关到后端）授权的双重身份验证模型，包括IAM（SigV4）和OAuth支持
自动工具发现：代理通过标准MCP在运行时动态发现可用工具 tools/list 接口
有状态的MCP支持：AgentCore Runtime支持高级有状态MCP功能，包括启发（服务器发起的多回合对话）、采样和实时进度通知
框架兼容性：适用于Strands代理、LangChain、LlamaIdex和其他流行的代理框架

主要优势

无额外操作负担：您不需要为每个API构建、部署或管理MCP服务器。创建一个网关，添加您的目标，AgentCore处理其余部分——全面管理MCP协议处理、转码和工具路由。

统一工具接口：在单个MCP端点后聚合来自多个后端源（REST API、Lambda、现有MCP服务器）的工具，简化代理开发并降低集成复杂性。

全面的工具安全：AgentCore确保所有代理交互都是安全的：

- 入站授权：控制哪些代理和客户端可以使用Amazon Cognito OAuth或IAM（SigV4）身份验证访问您的网关 - 出站授权：管理网关如何使用每个后端服务进行身份验证（API密钥、OAuth、IAM角色） - 将敏感凭据存储在 AWS机密管理器或系统管理器参数存储 - 为代理和用户强制最低权限IAM权限

集中工具目录：网关为代理大规模发现和搜索可用工具提供了一个稳定的入口点。工具通过标准MCP协议进行索引和发现。

支持的目标类型

目标类型	描述	用例
AWS Lambda	通过Lambda函数执行自定义业务逻辑	自定义工具实现、无服务器后端
OpenAPI架构	使用OpenAPI 3.0/3.1规范将REST API转换为MCP工具	现有的REST API、第三方服务
史密斯模型	使用Smithy IDL	AWS服务集成、强类型API定义结构化API接口
MCP服务器	将现有MCP服务器中的工具合并为本机目标	预构建的MCP服务器、第三方MCP工具
内置模板	预配置的集成模板	Salesforce、Slack、Jira、Asana、Zendesk

运作原理

创建网关：使用AWS控制台、AgentCore CLI或 CreateGateway API创建网关端点，作为代理的统一MCP接口。

添加目标：在网关上配置一个或多个目标。每个目标将一个后端服务（Lambda、RESTneneneba API、MCP服务器）映射到网关，定义请求的路由和身份验证方式。

工具索引：网关使用 SynchronizeGatewayTargets API执行协议握手并为每个目标的可用工具编制索引。这可以是隐式的（自动）或显式的（手动刷新）。

连接代理：将您的AI代理指向网关的MCP端点。代理通过以下方式动态发现工具 tools/list 并通过以下方式调用它们 tools/call --全部通过标准MCP协议。

先决条件

可访问Amazon Bedrock AgentCore的AWS帐户
AWS CLI已安装并配置了适当的权限
Python 3.11+或Node.js 20+（用于服务器开发）
已安装Docker（用于容器化部署到AgentCore运行时）
将现有后端服务作为工具公开：

- 符合OpenAPI 3.0/3.1规范的REST API，或 - AWS Lambda函数具有工具模式，或者 - 具有流式HTTP传输的现有MCP服务器

入门指南

1.创建网关

使用AWS CLI：

aws bedrock-agentcore-control create-gateway \
  --name "my-api-gateway" \
  --description "MCP gateway for my existing APIs"

或者使用AWS控制台通过图形界面创建网关，该界面允许您一步配置授权、定义网关和添加目标。

2.添加目标

将现有API添加为网关上的目标。配置取决于您的目标类型：

对于REST API（OpenAPI）：

准备一个描述API的OpenAPI 3.0或3.1规范文件
将规范上传到S3存储桶或内联提供
这 operationId 在规范中成为MCP工具名称

对于Lambda函数：

提供Lambda函数ARN
定义描述输入和输出的工具模式

对于现有的MCP服务器：

提供MCP服务器端点URL
网关执行协议握手以索引可用工具

3.配置身份验证

设置双重身份验证模型：

入站（代理到网关）：

配置OAuth授权器（例如Amazon Cognito）以供生产使用
或者，使用IAM（SigV4）进行服务间通信

出站（后端网关）：

为每个目标配置凭据（API密钥、OAuth令牌、IAM角色）
将机密存储在AWS secrets Manager或Systems Manager参数存储中

4.同步和验证

将网关目标同步到索引可用工具：

aws bedrock-agentcore-control synchronize-gateway-targets \
  --gateway-id "your-gateway-id"

5.连接您的代理

一旦网关上线，它将提供一个受管理的MCP端点URL。将您的代理连接到此URL，它将动态发现所有可用的工具。

在AgentCore运行时部署MCP服务器

如果您需要托管自定义MCP服务器，AgentCore Runtime提供了一个完全托管的无服务器托管环境：

1.将MCP服务器容器化：

确保您的服务器支持流式HTTP传输
将其配置为监听 0.0.0.0:8000/mcp （默认AgentCore端点）

2.推送到亚马逊ECR：

# Create an ECR repository
aws ecr create-repository --repository-name my-mcp-server

# Build, tag, and push your container image
docker build -t my-mcp-server .
docker tag my-mcp-server:latest .dkr.ecr..amazonaws.com/my-mcp-server:latest
docker push .dkr.ecr..amazonaws.com/my-mcp-server:latest

3.部署到AgentCore运行时：

aws bedrock-agentcore-control create-agent-runtime \
  --agent-runtime-name "my-mcp-runtime" \
  --agent-runtime-artifact '{ "containerConfiguration": { "containerUri": "" } }' \
  --role-arn "arn:aws:iam:::role/AgentCoreExecutionRole"

4.注册为网关目标：

将部署的运行时作为目标添加到AgentCore网关中，以进行集中管理和工具发现。

MCP客户端配置

适用于Amazon Q开发者命令行界面

编辑 ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "agentcore-gateway": {
      "type": "http",
      "url": "https://your-agentcore-gateway-endpoint-url/mcp",
      "env": {
        "AWS_REGION": "us-east-1",
        "AUTH_TOKEN": "your-cognito-or-iam-token"
      }
    }
  }
}

适用于克劳德桌面

编辑配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentcore-gateway": {
      "type": "http",
      "url": "https://your-agentcore-gateway-endpoint-url/mcp",
      "env": {
        "AWS_REGION": "us-east-1",
        "AUTH_TOKEN": "your-cognito-or-iam-token"
      }
    }
  }
}

重要提示： 更新配置后，完全退出MCP客户端并重新启动。

备注：如果您的AgentCore网关使用IAM（SigV4）身份验证，则可以使用 AWS的MCP代理作为自动处理SigV4请求签名的客户端网桥。请参阅下面的补充部分。

______________________________________________________________________

补充：AWS的MCP代理（SigV4网桥）

这 AWS的MCP代理是MCP客户端（如Claude Desktop、Amazon Q Developer CLI）和AWS上使用SigV4身份验证的IAM安全MCP服务器之间的轻量级客户端网桥。当您的AgentCore网关或其他AWS托管的MCP服务器需要SigV4签名时，请使用此功能。

先决条件：

Python 3.10或更高版本
uv 已安装包管理器(安装指南)
AWS CLI已安装并配置了有效凭据

快速入门：

uvx mcp-proxy-for-aws@latest https://your-agentcore-gateway-endpoint-url/mcp

使用SigV4代理的客户端配置（Amazon Q Developer CLI）：

{
  "mcpServers": {
    "aws-mcp-server": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://your-agentcore-gateway-endpoint-url/mcp",
        "--profile",
        "default",
        "--region",
        "us-east-1",
        "--log-level",
        "INFO"
      ]
    }
  }
}

使用SigV4代理的客户端配置（克劳德桌面）：

{
  "mcpServers": {
    "aws-api": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://your-agentcore-gateway-endpoint-url/mcp",
        "--profile",
        "default",
        "--region",
        "us-east-1"
      ]
    }
  }
}

有关其他代理选项（Docker、配置参数、环境变量），请参阅 AWS存储库的MCP代理.

附加资源

故障排除

问题：“创建网关失败”或权限错误

解决方案：验证您的AWS帐户是否可以访问Amazon Bedrock AgentCore
确保您的IAM用户/角色具有必要的 bedrock-agentcore-control:* 权限
检查您选择的AWS地区是否提供该服务

问题：添加目标后工具发现失败

解决方案：运行 SynchronizeGatewayTargets 刷新工具索引
验证您的OpenAPI规范是有效的OpenAPI 3.0或3.1（不支持Swagger 2.0）
确保Lambda函数可访问，并且工具架构定义正确
对于MCP服务器目标，验证端点是否响应MCP协议握手

问题：“无法找到凭据”（使用AWS的MCP代理时）

解决方案：验证AWS CLI是否配置了 aws configure 或者环境变量设置正确
检查凭据优先级：环境变量>配置文件>IAM角色
使用以下工具测试AWS凭据： aws sts get-caller-identity

问题：“拒绝访问”或403错误

解决方案：检查入站和出站授权配置
验证代理的OAuth令牌或IAM凭据是否有效
确保网关的IAM执行角色有权调用后端目标
对于SigV4端点，请确保 --service 参数正确（例如。， execute-api API网关）

问题：连接超时或504错误

解决方案：AgentCore网关的调用有5分钟的超时时间——确保后端操作在此限制内完成
验证网络连接并检查VPC配置是否允许出站访问
对于长时间运行的任务，考虑将结果写入Amazon Bedrock AgentCore Memory

问题：MCP服务器容器未在AgentCore运行时启动

解决方案：验证您的容器映像是否处于侦听状态 0.0.0.0:8000/mcp
检查容器健康检查和端口配置
查看AgentCore运行时日志以了解详细的错误消息
确保ECR映像URI正确，并且执行角色可以从ECR中提取

问题：从客户端“连接到MCP服务器失败”

解决方案：验证网关端点URL是否可以从您的计算机访问
检查MCP客户端中的身份验证配置
确保没有防火墙或代理阻止连接
使用以下工具测试端点 curl 确认是否可以联系到

有关更多故障排除帮助，请参阅 Agent核心文档

______________________________________________________________________

安全最佳实践

凭据管理

从不将凭据提交到版本控制

- 使用 .env 文件并将其添加到 .gitignore - 对敏感数据使用环境变量 - 定期轮换API密钥和机密

使用最低权限访问

- 仅授予每个MCP服务器所需的最小权限 - 创建专用服务帐户或IAM角色 - 定期审核和审查权限

安全的凭证存储

- AWS：使用AWS Secrets Manager或Systems Manager参数存储 - Azure：使用Azure密钥库 - GCP：使用密钥管理器 - 本地开发：使用1Password或LastPass等安全凭据管理器

网络安全

仅使用HTTPS

- 切勿通过未加密的HTTP暴露MCP服务器 - 验证SSL/TLS证书 - 使用强密码套件

实施速率限制

- 防止滥用和DDoS攻击 - 根据预期使用情况配置适当的限制 - 监控异常交通模式

限制网络访问

- 使用防火墙规则限制对受信任IP范围的访问 - 尽可能实施VPN或专用网络 - 将API网关用于其他安全层

验证和授权

使用强身份验证方法

- 面向用户的应用程序的OAuth 2.0 - 具有正确轮换策略的API密钥 - 使用短期令牌进行服务间身份验证

实施适当的授权

- 验证每个API操作的权限 - 使用基于角色的访问控制（RBAC） - 记录所有访问尝试以供审计

监控和日志记录

启用全面日志记录

- 记录所有API请求和响应（不包括敏感数据） - 监控失败的身份验证尝试 - 设置可疑活动警报

定期安全审计

- 定期查看访问日志 - 对MCP服务器配置进行安全评估 - 使用安全补丁使依赖关系保持最新

______________________________________________________________________

常见问题排查

连接问题

问题：无法连接到MCP服务器

检查表：

验证端点URL是否正确且可访问
检查网络连接 curl 或 telnet
确保防火墙规则允许出站连接
验证终结点域的DNS解析
启用详细日志记录的测试(--log-level DEBUG AWS）

身份验证失败

问题：401未经授权或403禁止的错误

检查表：

验证凭据是否配置正确
检查凭证过期情况（特别是临时令牌）
确保服务帐户具有必要的权限
验证API密钥或订阅密钥处于活动状态
与MCP连接分开测试身份验证

性能问题

问题：响应时间慢或超时

检查表：

检查端点的网络延迟
增加配置中的超时值
监控API后端性能
查看速率限制设置
考虑频繁访问数据的缓存策略

工具发现问题

问题：MCP客户端中未显示工具

检查表：

重新启动MCP客户端应用程序
验证MCP服务器是否正在运行且可访问
检查客户端配置文件是否存在语法错误
确保MCP服务器在其架构中正确公开工具
查看客户端日志中的错误消息

配置问题

问题：配置错误无效

检查表：

验证配置文件中的JSON语法
检查是否缺少必需的参数
验证文件路径是否绝对正确
确保环境变量设置正确
根据平台特定文档审查配置

API To MCP Server

快速接入

详细介绍

将现有API作为MCP服务器公开

快速入门指南

术语表

目录

邮递员

先决条件

生成MCP服务器

设置您的MCP服务器

启动MCP服务器

配置MCP客户端

故障排除

谷歌云平台（Apigee）

主要特点

主要优势

工作原理（原生MCP支持）

代理开发工具包（ADK）集成

替代方案：基于样本的方法

先决条件（基于样本）

入门（基于示例）

附加资源

故障排除

微软 Azure

先决条件

加入AI Gateway早期访问

重要配置说明

公开API作为MCP服务器

配置策略

在Visual Studio代码中添加MCP服务器

在代理模式下使用工具

故障排除

亚马逊云服务

主要特点

主要优势

支持的目标类型

运作原理

先决条件

入门指南

在AgentCore运行时部署MCP服务器

MCP客户端配置

补充：AWS的MCP代理（SigV4网桥）

附加资源

故障排除

安全最佳实践

凭据管理

网络安全

验证和授权

监控和日志记录

常见问题排查

连接问题

身份验证失败

性能问题

工具发现问题

配置问题

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP