Configuring Multi-AgentSpace Setups with SigV4 Authentication in AWS Agent Toolkit

Use AWS SigV4 authentication with the mcp-proxy-for-aws tool to route requests across multiple Agent Spaces by passing agent_space_id parameters, bypassing the single-space limitation of bearer tokens.

The AWS Agent Toolkit for AWS supports logical partitions called Agent Spaces that allow a single identity to interact with independent agent contexts. While bearer tokens lock you to a single space, configuring multi-AgentSpace setups with SigV4 authentication enables dynamic routing across spaces using IAM-signed requests. This approach leverages the uvx mcp-proxy-for-aws proxy to sign JSON-RPC calls, allowing the MCP server to resolve the correct target space based on the agent_space_id argument you provide.

Why SigV4 Authentication Is Required for Multi-AgentSpace Routing

Bearer tokens issued for the AWS Agent Toolkit are strictly scoped to a single Agent Space. According to the source code in plugins/aws-agents-for-devsecops/README.md, "Bearer tokens are scoped to a single AgentSpace. For multi-space routing (pass agent_space_id per tool call), switch to SigV4 auth"【/cache/repos/github.com/aws/agent-toolkit-for-aws/main/plugins/aws-agents-for-devsecops/README.md#L85-L96】.

SigV4 authentication removes this limitation by leveraging AWS IAM credentials to sign each HTTP request. When you provide valid AWS credentials, the proxy attaches the required Authorization: AWS4-HMAC-SHA256 header and X-Amz-Date timestamp, allowing the remote Agent Core to authenticate your identity and route the call to the specific space identified in the payload.

Architecture Overview

The multi-space configuration relies on five key components:

• AWS Credentials – Permanent access keys or temporary SSO-derived credentials provide the IAM identity used for signing.
• mcp-proxy-for-aws – A local proxy installed via uvx that intercepts plain HTTP JSON-RPC requests, applies SigV4 signing, and forwards them to the Agent Core endpoint.
• MCP Server Configuration (.mcp.json) – Stores the command configuration that invokes the proxy with service and region parameters.
• Agent Space Routing – The agent_space_id parameter added to tool calls (e.g., aws_devops_agent__chat) determines which logical space receives the request.
• list_agent_spaces Tool – Enumerates available spaces when connected via SigV4, returning IDs you can use for subsequent targeted calls.

Step-by-Step Configuration Guide

Prerequisites

Ensure you have uvx installed and valid AWS credentials configured:

uvx --version
aws sts get-caller-identity

If the identity check fails, configure an AWS profile or run aws sso login before proceeding.

Install the MCP Proxy

Install the signing proxy using uvx:

uvx install mcp-proxy-for-aws@latest

Configure AWS Credentials

Verify your credential chain works for the target region. The proxy relies on the standard AWS credential provider chain (environment variables, ~/.aws/credentials, or IAM roles).

Run the Setup Skill

Execute the interactive setup skill located at plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md【/cache/repos/github.com/aws/agent-toolkit-for-aws/main/plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md】:

claude run plugins/aws-agents-for-devsecops/skills/setup-devops-agent

The skill performs diagnostics by checking for existing .mcp.json entries and determines bearer_ready and sigv4_ready status (lines 54-56). When prompted, select SigV4 as the authentication mode to enable multi-space routing.

Configure .mcp.json for SigV4

The setup skill can automatically write the configuration, or you can manually create the entry in .mcp.json. Replace <REGION> with your AWS region (e.g., us-east-1):

{
  "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>"
      ]
    }
  }
}

This configuration is derived from the SigV4 config section in plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md (lines 62-78)【/cache/repos/github.com/aws/agent-toolkit-for-aws/main/plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md#L62-L78】.

Verify Connectivity

Validate the SigV4 connection by sending a JSON-RPC initialization sequence through the proxy:

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.<REGION>.api.aws/mcp" \
  --service aidevops --region "<REGION>"
'

Successful output contains "result":{"tools":[...]} (see lines 24-27 of the skill file).

Discover and Target Agent Spaces

Once connected, invoke the list_agent_spaces tool to retrieve accessible space IDs:

aws_devops_agent__list_agent_spaces()

Sample output:

{
  "agent_spaces": [
    {"id": "as-prod-12345", "name": "Prod"},
    {"id": "as-stage-67890", "name": "Stage"}
  ]
}

Target a specific space by including the agent_space_id parameter in any tool call:

aws_devops_agent__chat(
    message="Summarize the services and runbooks in this space.",
    agent_space_id="as-prod-12345"
)

Practical Code Examples

End-to-End Bash Setup

This script automates the full configuration flow:

# Verify prerequisites

uvx --version || pip install uvx
aws sts get-caller-identity || echo "Configure AWS credentials first"

# Run interactive setup (selects SigV4 automatically if chosen)

claude run plugins/aws-agents-for-devsecops/skills/setup-devops-agent

# Verify the configuration was written

cat .mcp.json

# List available spaces

aws_devops_agent__list_agent_spaces

# Execute chat in specific space

aws_devops_agent__chat \
  message="Give me a quick health summary." \
  agent_space_id="as-prod-12345"

Sample .mcp.json Configuration

Production-ready configuration for us-east-1:

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

Listing and Targeting Spaces

From a Claude prompt, discover spaces:

> list_agent_spaces()

Result:

{
  "agent_spaces": [
    {"id":"as-abc123","name":"Dev"},
    {"id":"as-def456","name":"Prod"}
  ]
}

Then target the production space:

> aws_devops_agent__chat(
    message="What AWS resources are in this space?",
    agent_space_id="as-def456"
  )

The multi-space coordination logic is implemented in plugins/aws-agents-for-devsecops/skills/coordinating-multi-space-devops-agent/SKILL.md, which demonstrates looping over spaces and calling tools with the agent_space_id parameter【/cache/repos/github.com/aws/agent-toolkit-for-aws/main/plugins/aws-agents-for-devsecops/skills/coordinating-multi-space-devops-agent/SKILL.md】.

Summary

• Bearer tokens restrict you to a single Agent Space, while SigV4 authentication enables routing across multiple spaces using IAM credentials.
• Install mcp-proxy-for-aws via uvx to handle AWS4-HMAC-SHA256 request signing automatically.
• Configure .mcp.json with a command entry that invokes the proxy, specifying the Agent Core endpoint, service name, and region.
• Use list_agent_spaces to discover available spaces, then pass agent_space_id to any tool call to target a specific logical partition.
• Reference the setup skill at plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md for automated configuration and connectivity verification.

Frequently Asked Questions

What is the difference between bearer token and SigV4 authentication in Agent Toolkit?

Bearer tokens are OAuth tokens scoped to a single Agent Space, preventing cross-space routing. SigV4 authentication uses AWS IAM credentials to sign requests, allowing the MCP server to route calls to any space you specify via the agent_space_id parameter. As documented in the README, you must switch to SigV4 for multi-space workflows【/cache/repos/github.com/aws/agent-toolkit-for-aws/main/plugins/aws-agents-for-devsecops/README.md#L85-L96】.

How do I install the mcp-proxy-for-aws tool?

Install the proxy using the uvx package manager: uvx install mcp-proxy-for-aws@latest. The tool runs as a command-line wrapper that accepts JSON-RPC on stdin, signs the HTTP request with SigV4, and forwards it to the specified Agent Core endpoint.

Can I switch between Agent Spaces without restarting the MCP server?

Yes. When using SigV4 authentication, you can change the agent_space_id parameter on a per-call basis. Simply pass a different space ID to each tool invocation (e.g., aws_devops_agent__chat) to route the request to a different logical space without modifying the .mcp.json configuration or restarting the server.

Where is the multi-space coordination logic implemented?

The coordination logic for iterating across multiple spaces and executing tools with specific agent_space_id values is defined in plugins/aws-agents-for-devsecops/skills/coordinating-multi-space-devops-agent/SKILL.md【/cache/repos/github.com/aws/agent-toolkit-for-aws/main/plugins/aws-agents-for-devsecops/skills/coordinating-multi-space-devops-agent/SKILL.md】. This skill demonstrates how to query list_agent_spaces and loop through results to aggregate data from independent agent contexts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}