generate-mcp-server

generate-mcp-server

使用 Speakeasy 从 OpenAPI 规范生成 Model Context Protocol（MCP）服务。该 MCP 服务会将 API 操作公开为工具，供 Claude 等 AI 助手直接调用。

适用场景

• 用户想从自己的 API 创建 MCP 服务
• 用户询问 Model Context Protocol 集成
• 用户想让 AI 助手与自己的 API 交互
• 用户说：“generate MCP server”、“create MCP server”、“speakeasy MCP”
• 用户询问：“如何让 Claude 使用我的 API？”
• 用户提到：“mcp-typescript”、“AI assistant tools”、“Claude tools”

输入

输入	必需	说明
OpenAPI 规范	是	OpenAPI 规范的路径或 URL
包名	是	MCP 服务的 npm 包名（例如，my-api-mcp）
身份验证方法	是	API 的身份验证方式（Bearer 令牌、API 密钥等）
环境变量前缀	否	环境变量的前缀（例如，MYAPI）
Scope 策略	否	将操作映射到 scope 的方式（默认：按 HTTP 方法区分读/写）

输出

输出	说明
MCP 服务	每个 API 操作对应一个工具的 TypeScript MCP 服务
CLI 入口点	支持 stdio 和 SSE 传输的命令行界面
Scope 定义	基于 scope 的访问控制，用于筛选工具
Docker 支持	用于容器化部署的 Dockerfile 和 compose 配置
工作流配置	配置为用于 MCP 生成的 .speakeasy/workflow.yaml

前提条件

1. 已安装并完成身份验证的 Speakeasy CLI：

speakeasy auth login
# Or for CI/AI agents:
export SPEAKEASY_API_KEY="<your-api-key>"

2. 已安装 Node.js 20+（用于生成的 MCP 服务）。

3. 有效的 OpenAPI 规范（3.0 或 3.1）。请先验证：

speakeasy lint openapi --non-interactive -s ./openapi.yaml

运行 speakeasy auth login 以交互方式完成身份验证，或设置 SPEAKEASY_API_KEY 环境变量。

命令

配置工作流、覆盖文件和 gen.yaml 后，生成过程会使用 speakeasy run。这没有单一命令——请按照以下分步工作流操作。

# After all config files are in place:
speakeasy run

分步工作流

步骤 1：创建 Scopes 覆盖文件

在项目根目录下创建 mcp-scopes-overlay.yaml。此文件用于控制哪些 API 操作会成为 MCP 工具，以及它们需要哪些 scope：

# mcp-scopes-overlay.yaml
openapi: 3.1.0
overlay: 1.0.0
info:
  title: Add MCP scopes
  version: 0.0.0
actions:
  # Enable read operations
  - target: $.paths.*["get","head"]
    update:
      x-speakeasy-mcp:
        scopes: [read]
        disabled: false

  # Enable write operations
  - target: $.paths.*["post","put","delete","patch"]
    update:
      x-speakeasy-mcp:
        scopes: [write]
        disabled: false

  # Disable specific sensitive endpoints (customize as needed)
  # - target: $.paths["/admin/danger-zone"]["delete"]
  #   update:
  #     x-speakeasy-mcp:
  #       disabled: true

步骤 2：创建工作流配置

创建 .speakeasy/workflow.yaml：

# .speakeasy/workflow.yaml
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  My-API:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: mcp-scopes-overlay.yaml
    output: openapi.yaml
targets:
  mcp-server:
    target: mcp-typescript
    source: My-API

将 ./openapi.yaml 替换为实际的规范路径或 URL。

重要： 使用独立的 mcp-typescript target，而不是启用了 enableMCPServer: true 的 typescript。嵌入式方式（enableMCPServer 标志）已弃用。

步骤 3：配置 gen.yaml

创建 .speakeasy/gen.yaml：

# .speakeasy/gen.yaml
configVersion: 2.0.0
generation:
  sdkClassName: MyApiMcp
  maintainOpenAPIOrder: true
  devContainers:
    enabled: true
    schemaPath: ./openapi.yaml
typescript:
  version: 1.0.0
  packageName: my-api-mcp
  envVarPrefix: MYAPI

关键设置：

• workflow.yaml 中的 target: mcp-typescript——此设置会触发 MCP 服务生成
• packageName——用户将通过 npx 运行的 npm 包名
• envVarPrefix——自动生成的环境变量名称前缀

步骤 4：生成

speakeasy run

如需适合 AI 使用的输出：

speakeasy run --output console 2>&1 | tail -50

使用生成的 MCP 服务

CLI 用法

# Start with stdio transport (default, for local AI assistants)
npx my-api-mcp mcp start --bearer-auth "YOUR_TOKEN"

# Start with SSE transport (for networked deployment)
npx my-api-mcp mcp start --transport sse --port 3000 --bearer-auth "YOUR_TOKEN"

# Filter by scope (only expose read operations)
npx my-api-mcp mcp start --scope read --bearer-auth "YOUR_TOKEN"

# Mount specific tools only
npx my-api-mcp mcp start --tool users-get-users --tool users-create-user --bearer-auth "YOUR_TOKEN"

CLI 选项

标志	说明	默认值
--transport	传输类型：stdio 或 sse	stdio
--port	SSE 传输的端口	2718
--bearer-auth	API 身份验证令牌	必需
--server-url	覆盖 API 基础 URL	取自规范
--scope	按 scope 筛选（可重复指定）	所有 scope
--tool	挂载指定工具（可重复指定）	所有工具
--log-level	日志级别	info

Claude Desktop 配置

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y", "--package", "my-api-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}

Claude Code 配置

添加到 .claude/settings.json，或使用 claude mcp add：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y", "--package", "my-api-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}

Docker 部署

生产环境请使用 Docker 和 SSE 传输：

# Build and run
docker-compose up -d

# Configure MCP client to use SSE endpoint
# "url": "http://localhost:32000/sse"

生成的项目包含 Dockerfile 和 docker-compose.yaml。

示例

为宠物商店 API 生成 MCP 服务的完整示例：

# 1. Validate the spec
speakeasy lint openapi --non-interactive -s ./petstore.yaml

# 2. Create scopes overlay
cat > mcp-scopes-overlay.yaml << 'EOF'
openapi: 3.1.0
overlay: 1.0.0
info:
  title: Add MCP scopes
  version: 0.0.0
actions:
  - target: $.paths.*["get","head"]
    update:
      x-speakeasy-mcp:
        scopes: [read]
        disabled: false
  - target: $.paths.*["post","put","delete","patch"]
    update:
      x-speakeasy-mcp:
        scopes: [write]
        disabled: false
EOF

# 3. Create workflow (assumes .speakeasy/ dir exists)
mkdir -p .speakeasy
cat > .speakeasy/workflow.yaml << 'EOF'
workflowVersion: 1.0.0
speakeasyVersion: latest
sources:
  petstore:
    inputs:
      - location: ./petstore.yaml
    overlays:
      - location: mcp-scopes-overlay.yaml
    output: openapi.yaml
targets:
  mcp-server:
    target: mcp-typescript
    source: petstore
EOF

# 4. Create gen.yaml
cat > .speakeasy/gen.yaml << 'EOF'
configVersion: 2.0.0
generation:
  sdkClassName: PetStoreMcp
  maintainOpenAPIOrder: true
typescript:
  version: 1.0.0
  packageName: petstore-mcp
  envVarPrefix: PETSTORE
EOF

# 5. Generate
speakeasy run

# 6. Test locally
npx petstore-mcp mcp start --bearer-auth "test-token"

预期输出

Workflow completed successfully.
Generated TypeScript MCP server in ./

生成的项目包含：

• src/mcp-server/server.ts -- MCP 服务主工厂
• src/mcp-server/tools/ -- 每个 API 操作对应一个工具
• src/mcp-server/mcp-server.ts -- CLI 入口点
• src/mcp-server/scopes.ts -- Scope 定义

最佳实践

1. 使用 overlay 配置 MCP -- 切勿直接编辑源 OpenAPI 规范
2. 完善面向 AI 的描述 -- 添加文档 overlay，帮助 AI 助手理解工具的用途
3. 在运行时筛选工具 -- 使用 --scope 和 --tool 标志限制公开的内容
4. 使用环境变量 -- 切勿在配置文件中硬编码令牌
5. 从只读 scope 开始 -- 仅在需要时添加写入 scope
6. 创建专用的 MCP 包 -- 将 MCP 与主 SDK 分开

不要这样做

• 不要修改源 OpenAPI 规范来添加 x-speakeasy-mcp -- 请改用 overlay
• 不要在 Claude Desktop 或 Claude Code 配置文件中硬编码 API 令牌 -- 请使用环境变量或密钥管理器
• 不要在未经审核的情况下公开所有操作 -- 禁用敏感的管理端点
• 不要跳过规范验证 -- 无效的规范会导致 MCP 服务无法正常工作
• 不要在 gen.yaml 中使用已弃用的 enableMCPServer: true 标志 -- 请改用 workflow.yaml 中独立的 mcp-typescript target
• 不要在没有 scope overlay 的情况下生成 -- 工具将缺少 scope 定义
• 不要将生成的 MCP 服务用作通用 SDK -- 它专为 AI 助手集成而设计

故障排除

MCP 服务无法启动

症状： npx my-api-mcp mcp start 立即报错。

原因： 缺少身份验证标志或标志无效。

解决方法：

# Ensure auth flag matches your API's auth scheme
npx my-api-mcp mcp start --bearer-auth "YOUR_TOKEN"

# Check --help for available auth flags
npx my-api-mcp mcp start --help

AI 助手中未显示任何工具

症状： MCP 服务已启动，但 AI 助手未显示任何工具。

原因： 缺少 x-speakeasy-mcp 扩展，或所有操作均已禁用。

解决方法： 确认 scopes overlay 已在 workflow.yaml 的 overlays: 下列出，并且操作的 disabled: false。

使用 mcp-typescript target 生成失败

症状： 使用 target: mcp-typescript 时，speakeasy run 失败。

原因： 通常是规范验证问题、缺少 workflow 配置，或使用了已弃用的 enableMCPServer 标志而非 mcp-typescript target。

解决方法：

# Validate spec first
speakeasy lint openapi --non-interactive -s ./openapi.yaml

# Ensure workflow.yaml uses target: mcp-typescript (NOT target: typescript with enableMCPServer)
cat .speakeasy/workflow.yaml

# Remove enableMCPServer from gen.yaml if present -- it is deprecated

工具缺少预期操作

症状： 某些 API 操作未作为 MCP 工具提供。

原因： 操作未被 scopes overlay 的目标选择器选中，或已被显式禁用。

解决方法： 检查 mcp-scopes-overlay.yaml 中的目标选择器。确保路径和方法与规范匹配。