setup-devops-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AWS DevOps Agent — Claude Setup

AWS DevOps Agent — Claude 设置指南

The instructions below are specifically for setting up the AWS DevOps Agent plugin for Claude applications. For other clients, use this as a reference, but adjust the instructions based on the client's specific requirements.

以下说明专门针对Claude应用的AWS DevOps Agent插件设置。对于其他客户端，可将本文作为参考，并根据客户端的具体要求调整说明内容。

Step 0: Check if setup is needed

步骤0：检查是否需要设置

1/ Check if the "aws-devops-agent" MCP server is running. If it is, verify that it has a valid connection (see "Step 3: Verify connectivity").

If verification is successful, you should inform the user that the plugin is already setup using

SigV4 or Bearer Token

. Offer that you can switch the configuration to

Bearer Token or SigV4

, see "Step 2: Decide auth path" below for details.

If the user does not want to change their auth configuration, then you are DONE STOP HERE.

2/ Check for an MCP server config with a key "aws-devops-agent" in the following locations:

Plugin scoped:
```
${CLAUDE_PLUGIN_ROOT}/.mcp.json
```
Project-scoped: .mcp.json (in your project directory, version-controlled)
Project-specific: .claude/settings.local.json (in your project directory)
User-specific local: ~/.claude/settings.local.json
User-specific global: ~/.claude/settings.json
Main Claude.json: ~/.claude.json
Dedicated MCP file: ~/.claude/mcp_servers.json

Then:

If
```
aws-devops-agent
```
key exists AND the server is connected (tools are available, see "Step 3: Verify connectivity") → Inform the user: "DevOps Agent is already configured and connected."; If Bearer Token is used in the MCP config, suggest that you can alternatively setup the plugin to use SigV4 credentials for the AWS DevOps Agent (multiple agent spaces, admin tooling). If SigV4 credentials are used in the MCP config, suggest that you can alternatively setup the plugin to use Bearer Token credentials for the AWS DevOps Agent (single agent space).
If
```
aws-devops-agent
```
key exists but is failing → continue to "Step 1: Diagnose current state"
If
```
aws-devops-agent
```
key does NOT exist → continue to "Step 1: Diagnose current state"

1/ 检查"aws-devops-agent" MCP服务器是否正在运行。如果正在运行，请验证其是否具有有效连接（参见“步骤3：验证连通性”）。

如果验证成功，你应告知用户该插件已通过

SigV4或Bearer Token

完成设置。可询问用户是否需要将配置切换为

Bearer Token或SigV4

，详情请见下方“步骤2：选择认证方式”。

如果用户不想更改其认证配置，则流程到此结束。

2/ 在以下位置检查是否存在包含"aws-devops-agent"键的MCP服务器配置：

插件范围：
```
${CLAUDE_PLUGIN_ROOT}/.mcp.json
```
项目范围：项目目录下的.mcp.json（受版本控制）
项目特定：项目目录下的.claude/settings.local.json
用户本地：~/.claude/settings.local.json
用户全局：~/.claude/settings.json
主Claude配置：~/.claude.json
专用MCP文件：~/.claude/mcp_servers.json

然后：

若"aws-devops-agent"键存在且服务器已连接（工具可用，参见“步骤3：验证连通性”）→ 告知用户：“DevOps Agent已配置并连接。”；若MCP配置中使用的是Bearer Token，可建议用户将插件设置为使用SigV4凭证连接AWS DevOps Agent（支持多代理空间、管理工具）。若MCP配置中使用的是SigV4凭证，可建议用户将插件设置为使用Bearer Token凭证连接AWS DevOps Agent（单代理空间）。
若"aws-devops-agent"键存在但连接失败 → 继续执行“步骤1：诊断当前状态”
若"aws-devops-agent"键不存在 → 继续执行“步骤1：诊断当前状态”

Step 1: Diagnose current state

步骤1：诊断当前状态

Run these checks:

bash

undefined

运行以下检查：

bash

undefined

Bearer token

echo "DEVOPS_AGENT_TOKEN: $([ -n "$DEVOPS_AGENT_TOKEN" ] && echo 'set' || echo 'not set')" echo "DEVOPS_AGENT_REGION: ${DEVOPS_AGENT_REGION:-not set}"

SigV4 dependencies

uvx --version 2>&1

AWS credentials

aws sts get-caller-identity 2>&1


Determine:

- `bearer_ready` = `DEVOPS_AGENT_TOKEN` is set AND `DEVOPS_AGENT_REGION` is set
- `sigv4_ready` = `aws sts get-caller-identity` succeeds AND `uvx` is installed

---

aws sts get-caller-identity 2>&1


判断：

- `bearer_ready` = `DEVOPS_AGENT_TOKEN`已设置且`DEVOPS_AGENT_REGION`已设置
- `sigv4_ready` = `aws sts get-caller-identity`执行成功且`uvx`已安装

---

Step 2: Decide auth path

步骤2：选择认证方式

After diagnostics, ALWAYS ask the user which path they want — even if only one is available. Present what you found and let them choose.

The user may want to use bearer token if they only have access to the operator app for an agent space.

The user may want to use SigV4 if they use multiple agent spaces and/or have admin permissions to manage agent spaces.

Bearer ready	SigV4 ready	Action
yes	yes	"You have both a bearer token and AWS credentials configured. Which would you prefer for the DevOps Agent? Bearer token (single agent space) or AWS credentials / SigV4 (multiple agent spaces and admin tooling)?"
yes	no	"You have a bearer token configured. Would you like me to set up the DevOps Agent using your Bearer token (single agent space)? Or would you prefer to configure AWS credentials / SigV4 instead (multiple agent spaces and admin tooling)?"
no	yes	"You have valid AWS credentials. Would you like me to set up the DevOps Agent using SigV4 (multiple agent spaces and admin tooling)? Or would you prefer to set up a Bearer token instead (single agent space)?"
no	no	"Neither a bearer token nor AWS credentials are configured. Would you like to connect via Bearer token (single agent space) or AWS credentials / SigV4 (multiple agent spaces and admin tooling)?" Then guide them through the chosen path.

If the user would like to setup a bearer token, refer them to the AWS docs for Connect to DevOps Agent remote servers or walk them through the steps to create a access token from this document.

Do NOT proceed to Step 3 until the user confirms their choice.

完成诊断后，无论是否只有一种可用方式，都必须询问用户选择哪种方式。告知用户诊断结果并让其选择。

如果用户仅能访问某个代理空间的操作员应用，可能会选择使用Bearer token。

如果用户使用多个代理空间和/或拥有管理代理空间的管理员权限，可能会选择使用SigV4。

Bearer已就绪	SigV4已就绪	操作
是	是	“你已配置Bearer token和AWS凭证。你希望为DevOps Agent选择哪种方式？Bearer token（单代理空间）还是AWS凭证/SigV4（多代理空间及管理工具）？”
是	否	“你已配置Bearer token。是否希望我使用你的Bearer token（单代理空间）设置DevOps Agent？或者你更愿意配置AWS凭证/SigV4（多代理空间及管理工具）？”
否	是	“你拥有有效的AWS凭证。是否希望我使用SigV4（多代理空间及管理工具）设置DevOps Agent？或者你更愿意设置Bearer token（单代理空间）？”
否	否	“未配置Bearer token或AWS凭证。你希望通过Bearer token（单代理空间）还是AWS凭证/SigV4（多代理空间及管理工具）连接？”然后引导用户完成所选方式的设置。

如果用户希望设置Bearer token，请引导其查看AWS文档中的连接到DevOps Agent远程服务器，或根据本文内容引导其创建访问令牌。

在用户确认选择前，请勿进入步骤3。

Step 3: Verify connectivity

步骤3：验证连通性

If the "aws-devops-agent" MCP server is already running, check if you can list tools. If you can, then you have verified the connection.

Otherwise, proceed.

Verify BEFORE writing

.mcp.json

. This confirms the credentials work against the live endpoint. Or use this to verify an existing MCP server config.

如果"aws-devops-agent" MCP服务器已在运行，请检查是否能列出工具。如果可以，则已验证连接有效。

否则，请继续执行以下步骤。

在写入

.mcp.json

之前进行验证，确认凭证可在真实端点上正常工作。也可使用此方法验证现有MCP服务器配置。

Bearer verification

Bearer验证

bash

curl -s -w "\nHTTP_STATUS: %{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEVOPS_AGENT_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp"

Result	Meaning	Action
HTTP 200 + `result.tools` array	Success	Proceed to Step 4
HTTP 401	Token invalid or expired	Tell user to create a new token in the Operator Web App
HTTP 403	Token scope insufficient	Tell user token needs `agent:read` + `agent:operate` scopes
Connection refused / timeout	Endpoint unreachable	If SigV4 is available, offer fallback. Otherwise report unavailable.

bash

curl -s -w "\nHTTP_STATUS: %{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEVOPS_AGENT_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp"

结果	含义	操作
HTTP 200 + `result.tools` 数组	成功	进入步骤4
HTTP 401	令牌无效或已过期	告知用户在操作员Web应用中创建新令牌
HTTP 403	令牌权限不足	告知用户令牌需要 `agent:read` + `agent:operate` 权限
连接被拒绝/超时	端点不可达	如果SigV4可用，提供备选方案。否则报告服务不可用。

SigV4 verification

SigV4验证

bash

timeout 30 bash -c '
{
echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"setup-check\",\"version\":\"1.0\"}}}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"
sleep 8
} | uvx mcp-proxy-for-aws@latest "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp" --service aidevops --region "$DEVOPS_AGENT_REGION"
'

Note: The first run may take 10-15s as
uvx
downloads
mcp-proxy-for-aws
and its dependencies. Subsequent runs are near-instant.

Result	Meaning	Action
Second line contains `result.tools`	Success	Proceed to Step 4
No output / timeout	Credentials invalid or endpoint unreachable	Check `aws sts get-caller-identity` again
`ExpiredTokenException` in stderr	AWS session expired	Tell user to re-authenticate ( `aws sso login` or refresh creds)
`AccessDeniedException`	Missing IAM permissions	User needs DevOps Agent permissions on their role

bash

timeout 30 bash -c '
{
echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"setup-check\",\"version\":\"1.0\"}}}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}"
sleep 0.5
echo "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"
sleep 8
} | uvx mcp-proxy-for-aws@latest "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp" --service aidevops --region "$DEVOPS_AGENT_REGION"
'

注意: 首次运行可能需要10-15s，因为
uvx
会下载
mcp-proxy-for-aws
及其依赖项。后续运行几乎是即时的。

结果	含义	操作
第二行包含 `result.tools`	成功	进入步骤4
无输出 / 超时	凭证无效或端点不可达	再次检查 `aws sts get-caller-identity`
`ExpiredTokenException` 在标准错误中	AWS会话已过期	告知用户重新认证（ `aws sso login` 或刷新凭证）
`AccessDeniedException`	缺少IAM权限	用户的角色需要DevOps Agent权限

Step 4: Confirm and write

.mcp.json

步骤4：确认并写入

.mcp.json

Before writing, confirm with the user:

"I've verified connectivity. I'll now add the [Bearer token / SigV4] MCP server to the plugin's
.mcp.json
. Proceed?"

Only write after the user confirms. Write ONE server entry — never both. Install the MCP config in

${CLAUDE_PLUGIN_ROOT}/.mcp.json

. You can also offer to install the MCP server at the workspace level. The installation options are:

Plugin scoped:
```
${CLAUDE_PLUGIN_ROOT}/.mcp.json
```
(default)
Project-scoped: .mcp.json (in your project directory, version-controlled)
Project-specific: .claude/settings.local.json (in your project directory)

写入前，请与用户确认：

"我已验证连通性。现在将**[Bearer token / SigV4]** MCP服务器添加到插件的
.mcp.json
中。是否继续？"

仅在用户确认后再写入。只写入一个服务器条目——切勿同时写入两个。将MCP配置安装到

${CLAUDE_PLUGIN_ROOT}/.mcp.json

。你也可提供在工作区级别安装MCP服务器的选项。安装选项包括：

插件范围：
```
${CLAUDE_PLUGIN_ROOT}/.mcp.json
```
（默认）
项目范围：项目目录下的.mcp.json（受版本控制）
项目特定：项目目录下的.claude/settings.local.json

Bearer config

Bearer配置

json

{
  "mcpServers": {
    "aws-devops-agent": {
      "type": "http",
      "url": "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp",
      "headers": {
        "Authorization": "Bearer ${DEVOPS_AGENT_TOKEN}"
      },
      "timeout": 120000
    }
  }
}

json

{
  "mcpServers": {
    "aws-devops-agent": {
      "type": "http",
      "url": "https://connect.aidevops.${DEVOPS_AGENT_REGION}.api.aws/mcp",
      "headers": {
        "Authorization": "Bearer ${DEVOPS_AGENT_TOKEN}"
      },
      "timeout": 120000
    }
  }
}

SigV4 config

SigV4配置

Replace

<REGION>

with the user's actual region:

json

{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://connect.aidevops.<REGION>.api.aws/mcp",
        "--service", "aidevops",
        "--region", "<REGION>"
      ]
    }
  }
}

替换

<REGION>

为用户的实际区域：

json

{
  "mcpServers": {
    "aws-devops-agent": {
      "command": "uvx",
      "timeout": 120000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://connect.aidevops.<REGION>.api.aws/mcp",
        "--service", "aidevops",
        "--region", "<REGION>"
      ]
    }
  }
}

Fallback (aws-mcp)

备选方案（aws-mcp）

Only add if the primary

aws-devops-agent

endpoint is unreachable AND SigV4 credentials are available:

json

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "timeout": 100000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata",
        "AWS_REGION=us-east-1"
      ]
    }
  }
}

For Sigv4 only: After writing the new MCP config, inform the user that the MCP server has been written successfully. Proceed to the next step.

仅当主

aws-devops-agent

端点不可达且SigV4凭证可用时添加：

json

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "timeout": 100000,
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata",
        "AWS_REGION=us-east-1"
      ]
    }
  }
}

仅针对SigV4：写入新的MCP配置后，告知用户MCP服务器已成功写入。继续执行下一步。

Step 5: Multi-space routing (SigV4 only)

步骤5：多空间路由（仅SigV4）

After successful SigV4 setup, discover and configure AgentSpace routing:

Call
```
list_agent_spaces
```
via the newly connected MCP to discover available spaces
Present the list to the user
If multiple spaces exist, write a routing guide to
```
.claude/aws-agents-for-devsecops.md
```
:

markdown

undefined

成功设置SigV4后，发现并配置AgentSpace路由：

通过新连接的MCP调用
```
list_agent_spaces
```
来发现可用空间
向用户展示列表
如果存在多个空间，将路由指南写入
```
.claude/aws-agents-for-devsecops.md
```
：

markdown

undefined

AWS DevOps Agent — Routing Guide

AWS DevOps Agent — 路由指南

Space	Agent Space ID	Purpose
<name>	<id>	<ask user>


1. Instruct: pass `agent_space_id` on every tool call when targeting a specific space.

---

空间	Agent Space ID	用途
<name>	<id>	<询问用户>


1. 说明：当目标为特定空间时，在每次工具调用中传递`agent_space_id`。

---

Step 6: Reload plugin

步骤6：重新加载插件

Inform the user that they will need to run /reload-plugins to start the new MCP server. You may need to prompt the user to run it. Also mention that after restarting the MCP server they should try the following prompts:

setup multi-space routing (SigV4 only)
<list skill and prompt suggestions from ${CLAUDE_PLUGIN_ROOT}/README.md>

告知用户需要运行/reload-plugins来启动新的MCP服务器。你可能需要提示用户执行此操作。同时提及重启MCP服务器后，他们可以尝试以下提示：

设置多空间路由（仅SigV4）
<从${CLAUDE_PLUGIN_ROOT}/README.md中列出技能和提示建议>

Bearer token guidance (for users who need to create one)

Bearer token指南（针对需要创建令牌的用户）

Open the AWS DevOps Agent Operator Web App for your AgentSpace
Navigate to Settings → Access tokens → Generate token
Create a token with Permissions: Operate
Set environment variables:
bash
```
export DEVOPS_AGENT_TOKEN="<your-token>"
export DEVOPS_AGENT_REGION="<your-region>"
```
Available regions: https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-supported-regions.html
Restart Claude Code (it reads env vars from the shell that launched it)

Important: Without
Operate
permissions, the
chat
and
investigate
tools will be completely invisible — not just fail, but absent from the tool list.

打开你的AgentSpace对应的AWS DevOps Agent 操作员Web应用
导航至设置 → 访问令牌 → 生成令牌
创建一个具有**
```
Operate
```
**权限的令牌
设置环境变量：
bash
```
export DEVOPS_AGENT_TOKEN="<your-token>"
export DEVOPS_AGENT_REGION="<your-region>"
```
可用区域：https://docs.aws.amazon.com/devopsagent/latest/userguide/about-aws-devops-agent-supported-regions.html
重启Claude Code（它会从启动它的shell中读取环境变量）

重要提示: 没有
Operate
权限，
chat
和
investigate
工具将完全不可见——不仅会失败，还不会出现在工具列表中。

SigV4 guidance (for users who need to configure AWS credentials)

SigV4指南（针对需要配置AWS凭证的用户）

Install

uvx

if not present:

macOS:
```
brew install uv
```

Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Configure AWS credentials:

bash

aws configure sso --profile devops-agent
aws sso login --profile devops-agent
export AWS_PROFILE=devops-agent

Set the region:

bash

export DEVOPS_AGENT_REGION="<your-region>"

Verify:
```
aws sts get-caller-identity
```
The IAM role must have DevOps Agent permissions (e.g., managed policy with aidevops access)

Important: Unset
DEVOPS_AGENT_TOKEN
when using SigV4. If both are set, clients may attempt bearer auth instead of the signing proxy.

如果未安装

uvx

，请进行安装：

macOS：
```
brew install uv
```

Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

配置AWS凭证：

bash

aws configure sso --profile devops-agent
aws sso login --profile devops-agent
export AWS_PROFILE=devops-agent

设置区域：

bash

export DEVOPS_AGENT_REGION="<your-region>"

验证：
```
aws sts get-caller-identity
```
IAM角色必须具有DevOps Agent权限（例如，包含aidevops访问权限的托管策略）

重要提示: 使用SigV4时，请取消设置
DEVOPS_AGENT_TOKEN
。如果两者都已设置，客户端可能会尝试使用Bearer认证而非签名代理。

Troubleshooting

故障排除

Error	Cause	Fix
No tools visible	Token not set or Claude Code not restarted	Set `DEVOPS_AGENT_TOKEN` + `DEVOPS_AGENT_REGION` , restart
HTTP 401	Token invalid/expired	Create new token in Operator Web App
`chat` / `investigate` missing	Token scope is `agent:read` only	Create token with `agent:operate` scope
Connection refused / timeout	Endpoint unreachable	Check network; if SigV4 available, offer `aws-mcp` fallback
`ExpiredTokenException`	AWS session credentials expired	`aws sso login` or refresh credentials
`AccessDeniedException` (SigV4)	Missing IAM permissions	Use a role with DevOps Agent access
Proxy won't start	`uvx` not installed	`brew install uv` (macOS) or install per platform
Tools appear but calls timeout	Normal for `chat` (5-30s)	Ensure `"timeout": 120000` in mcp.json

错误	原因	修复方法
无工具可见	未设置令牌或未重启Claude Code	设置 `DEVOPS_AGENT_TOKEN` + `DEVOPS_AGENT_REGION` ，重启应用
HTTP 401	令牌无效/已过期	在操作员Web应用中创建新令牌
`chat` / `investigate` 工具缺失	令牌权限仅为 `agent:read`	创建具有 `agent:operate` 权限的令牌
连接被拒绝/超时	端点不可达	检查网络；如果SigV4可用，提供 `aws-mcp` 备选方案
`ExpiredTokenException`	AWS会话凭证已过期	`aws sso login` 或刷新凭证
`AccessDeniedException` （SigV4）	缺少IAM权限	使用具有DevOps Agent访问权限的角色
代理无法启动	未安装 `uvx`	`brew install uv` （macOS）或根据平台进行安装
工具可见但调用超时	`chat` 工具的正常情况（5-30s）	确保mcp.json中设置了 `"timeout": 120000`

setup-devops-agent

Original

Translation

AWS DevOps Agent — Claude Setup

AWS DevOps Agent — Claude 设置指南

Step 0: Check if setup is needed

步骤0：检查是否需要设置

Step 1: Diagnose current state

步骤1：诊断当前状态

Bearer token

Bearer token

SigV4 dependencies

SigV4 dependencies

AWS credentials

AWS credentials

Step 2: Decide auth path

步骤2：选择认证方式

Step 3: Verify connectivity

步骤3：验证连通性

Bearer verification

Bearer验证

SigV4 verification

SigV4验证

Step 4: Confirm and write .mcp.json

步骤4：确认并写入.mcp.json

Bearer config

Bearer配置

SigV4 config

SigV4配置

Fallback (aws-mcp)

备选方案（aws-mcp）

Step 5: Multi-space routing (SigV4 only)

步骤5：多空间路由（仅SigV4）

AWS DevOps Agent — Routing Guide

AWS DevOps Agent — 路由指南

Step 6: Reload plugin

步骤6：重新加载插件

Bearer token guidance (for users who need to create one)

Bearer token指南（针对需要创建令牌的用户）

SigV4 guidance (for users who need to configure AWS credentials)

SigV4指南（针对需要配置AWS凭证的用户）

Troubleshooting

故障排除

Step 4: Confirm and write
`.mcp.json`

步骤4：确认并写入
`.mcp.json`