# Configuring Multi-AgentSpace Setups with SigV4 Authentication in AWS Agent Toolkit > Configure multi AgentSpace setups with SigV4 authentication using mcp-proxy-for-aws. Route requests across Agent Spaces, bypassing single-space bearer token limits. - Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws) - Tags: how-to-guide - Published: 2026-07-02 --- **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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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: ```bash 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`: ```bash 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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】: ```bash claude run plugins/aws-agents-for-devsecops/skills/setup-devops-agent ``` The skill performs diagnostics by checking for existing [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json). Replace `` with your AWS region (e.g., `us-east-1`): ```json { "mcpServers": { "aws-devops-agent": { "command": "uvx", "timeout": 120000, "args": [ "mcp-proxy-for-aws@latest", "https://connect.aidevops..api.aws/mcp", "--service", "aidevops", "--region", "" ] } } } ``` This configuration is derived from the SigV4 config section in [`plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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: ```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..api.aws/mcp" \ --service aidevops --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: ```bash aws_devops_agent__list_agent_spaces() ``` Sample output: ```json { "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: ```bash 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: ```bash # 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`: ```json { "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: ```text > list_agent_spaces() ``` Result: ```json { "agent_spaces": [ {"id":"as-abc123","name":"Dev"}, {"id":"as-def456","name":"Prod"} ] } ``` Then target the production space: ```text > 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.