How to Configure Multi-AgentSpace with SigV4 Authentication in AWS Agent Toolkit

To configure multi-AgentSpace with SigV4 authentication, install the mcp-proxy-for-aws proxy via uvx, ensure valid AWS credentials are available in your environment, run the setup-devops-agent skill to generate a SigV4-based .mcp.json configuration, and then pass agent_space_id arguments to route tool calls to specific logical spaces.

The AWS Agent Toolkit for AWS enables developers to interact with multiple logical Agent Spaces—such as separate production and staging environments—using IAM-based request signing. Unlike bearer tokens that are scoped to a single AgentSpace, SigV4 authentication allows a single set of AWS credentials to access and route requests across multiple spaces by signing each JSON-RPC call. This guide explains how to enable SigV4 authentication using the proxy pattern implemented in the aws/agent-toolkit-for-aws repository.

Why SigV4 Authentication is Required for Multi-AgentSpace

Bearer tokens issued for the AWS Agent Toolkit are strictly scoped to a single AgentSpace. According to the source code in plugins/aws-agents-for-devsecops/README.md (lines 85-96), you cannot route calls across different spaces without re-authenticating when using bearer tokens because the token embeds the space identity.

SigV4 authentication removes this limitation by signing requests with your AWS credentials. The mcp-proxy-for-aws tool intercepts outgoing JSON-RPC calls, adds the required Authorization: AWS4-HMAC-SHA256 header and X-Amz-Date timestamp, and forwards the signed request to the Agent Core endpoint. The remote MCP server then resolves the target space from the agent_space_id parameter in the payload rather than from a token scope.

Architecture Components

Understanding how the components interact helps troubleshoot configuration issues:

• AWS Credentials: Your IAM identity (access key/secret or SSO-derived temporary credentials) provides the signing key used by the proxy.
• mcp-proxy-for-aws: This local proxy (installed via uvx) transforms plain HTTP requests into SigV4-signed requests before they reach the Agent Core.
• .mcp.json Configuration: When SigV4 is enabled, this file contains a command entry that launches the proxy with the appropriate service and region flags.
• Agent Space Routing: The plugin forwards your agent_space_id argument with each tool call, allowing the backend to route the signed request to the correct logical partition.

Step-by-Step Configuration Guide

1. Install the Proxy and Verify Credentials

Ensure you have uvx installed and AWS credentials configured in your environment:

uvx --version
aws sts get-caller-identity

If the AWS command fails, configure your profile or run aws sso login before proceeding.

2. Run the Setup Skill

Execute the setup-devops-agent skill located at plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md. This interactive workflow checks your existing .mcp.json and determines whether your environment is bearer_ready or sigv4_ready (see lines 54-56 of the skill file).

When prompted, select SigV4 as your authentication mode. The skill automatically writes the appropriate configuration to your .mcp.json file.

3. Configure the MCP Server Entry

The skill generates a command-based configuration that invokes the proxy. Your .mcp.json should resemble this structure (replace <REGION> with your AWS region):

{
  "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 snippet is adapted from the SigV4 configuration template in the setup skill (lines 62-78).

4. Verify the Connection

The skill performs a SigV4 verification step by sending a JSON-RPC initialize request followed by a tools/list call. You can replicate this manually to confirm connectivity:

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 a "result":{"tools":[...]} payload, confirming the proxy is correctly signing requests (as documented in the skill file lines 24-27).

5. Discover Available Agent Spaces

Once authenticated via SigV4, invoke the list_agent_spaces tool to retrieve the IDs you can target:

aws_devops_agent__list_agent_spaces()

The response includes space identifiers and names:

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

6. Route Requests to Specific Spaces

Target a specific Agent Space by including the agent_space_id argument in any tool call. For example:

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

The proxy signs the request, the Agent Core resolves the space from the payload, and the response is scoped to that specific logical partition.

Practical Implementation Examples

End-to-End Bash Setup

# Verify prerequisites

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

# Run the interactive setup skill

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

# Verify the generated configuration

cat .mcp.json

# List available spaces

aws_devops_agent__list_agent_spaces

# Issue a request to a specific space

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

Multi-Space Coordination Pattern

For workflows that iterate across multiple spaces, reference the coordinating skill at plugins/aws-agents-for-devsecops/skills/coordinating-multi-space-devops-agent/SKILL.md. This pattern loops through the output of list_agent_spaces and dispatches calls with the appropriate agent_space_id for each iteration.

Key Source Files Reference

File Path	Purpose
plugins/aws-agents-for-devsecops/README.md (lines 85-96)	Documents the limitation of bearer tokens and the requirement for SigV4 in multi-space scenarios
plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md	Contains the interactive workflow, credential checks, and SigV4 configuration templates
plugins/aws-agents-for-devsecops/commands/spaces.md	CLI reference for listing and probing Agent Spaces
plugins/aws-agents-for-devsecops/skills/coordinating-multi-space-devops-agent/SKILL.md	Implementation patterns for routing calls across multiple spaces
plugins/aws-agents/skills/agents-build/references/multi-agent.md	Confirms A2A protocol support for both SigV4 and OAuth authentication methods

Summary

• SigV4 enables multi-space access: Unlike bearer tokens, IAM-signed requests can target any Agent Space by including an agent_space_id parameter.
• Proxy-based signing: The uvx mcp-proxy-for-aws tool handles SigV4 signing automatically, requiring only standard AWS credentials in your environment.
• Configuration is skill-driven: The setup-devops-agent skill validates your credentials and writes the correct .mcp.json command configuration.
• Discovery via list_agent_spaces: This tool is only available when using SigV4 authentication and returns the IDs needed for multi-space routing.
• Routing is argument-based: Pass agent_space_id to any tool call (such as aws_devops_agent__chat) to scope the request to a specific logical space.

Frequently Asked Questions

What is the difference between bearer token and SigV4 authentication for Agent Spaces?

Bearer tokens are OAuth tokens scoped to a single AgentSpace, meaning you must re-authenticate to switch spaces. SigV4 authentication uses AWS credentials to sign requests, allowing the same identity to access multiple spaces by passing different agent_space_id values in the JSON-RPC payload. The Agent Core verifies the signature and routes the request based on the parameter rather than token scope.

How do I discover available Agent Spaces when using SigV4 authentication?

When configured with SigV4, the MCP server exposes the list_agent_spaces tool (documented in plugins/aws-agents-for-devsecops/commands/spaces.md). Call this tool without arguments to receive a JSON list containing id and name fields for each space your IAM identity can access. This tool is unavailable when using bearer token authentication.

Can I use AWS SSO temporary credentials with the mcp-proxy-for-aws proxy?

Yes. The proxy uses the standard AWS credential chain, which supports SSO-derived temporary credentials, environment variables, and EC2 instance profiles. Run aws sso login before starting your MCP client to ensure valid credentials are cached, then verify with aws sts get-caller-identity. The proxy automatically reads these credentials to sign requests.

What should I do if the proxy verification step fails with a connection timeout?

First, confirm your AWS credentials are valid and not expired. Next, verify the --region parameter in your .mcp.json matches the region where your Agent Spaces are provisioned. Finally, ensure uvx can reach the endpoint https://connect.aidevops.<REGION>.api.aws/mcp from your network environment. The verification script in plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md (lines 24-27) expects a response within the timeout window; increase the timeout value in your .mcp.json (specified in milliseconds) if your network latency is high.

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