# How to Configure Multi-AgentSpace with SigV4 Authentication in AWS Agent Toolkit > Learn to configure multi-AgentSpace with SigV4 authentication in the AWS Agent Toolkit. Install the MCP proxy, set up credentials, and route tool calls efficiently using agent_space_id. - Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws) - Tags: how-to-guide - Published: 2026-06-26 --- **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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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: ```bash 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/skills/setup-devops-agent/SKILL.md). This interactive workflow checks your existing [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) file. ### 3. Configure the MCP Server Entry The skill generates a `command`-based configuration that invokes the proxy. Your [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) should resemble this structure (replace `` with your AWS region): ```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 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: ```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 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: ```bash aws_devops_agent__list_agent_spaces() ``` The response includes space identifiers and names: ```json { "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: ```bash 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 ```bash # 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) matches the region where your Agent Spaces are provisioned. Finally, ensure `uvx` can reach the endpoint `https://connect.aidevops..api.aws/mcp` from your network environment. The verification script 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 24-27) expects a response within the timeout window; increase the `timeout` value in your [`.mcp.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.mcp.json) (specified in milliseconds) if your network latency is high.