MCP tool forwarding

With Model Context Protocol (MCP) tool forwarding, agents can work directly with the applications and operating system running on the desktop. They make direct MCP calls instead of using computer-use tools. When you turn on tool forwarding, the MCP server forwards the tools set up on the WorkSpaces Applications session to your agent.

Setting up tool forwarding

To set up MCP tool forwarding:

Step 1: Enable tool forwarding

Turn on the FORWARD_MCP_TOOLS agent action through the API or console settings.

Step 2: Add the configuration file to the fleet's image

WorkSpaces Applications creates each streaming instance from the fleet's image, so the configuration file must be part of that image. Add it when you build or update the image. A file placed on a running instance does not carry over to new sessions. The service looks for the file at the following location, which depends on the platform:

Platform	Configuration file path
Windows instances	C:\ProgramData\NICE\dcv\mcp_server_redirection_config.json
Linux instances	/etc/dcv/mcp_server_redirection_config.json

Tool forwarding works the same way on image builders. Add the same configuration file, at the same location, to the image that you launch the image builder from.

Step 3: Define the MCP servers in the configuration file

The configuration file is JSON with a single top-level mcpServers object. Each key is a unique name that you choose for a server. Each value specifies how to launch that server.

The following example is for a Windows instance:

{
    "mcpServers": {
        "filesystem": {
            "command": "C:/path/to/python.exe",
            "args": ["C:/mcpServerPath/filesystem.py", "C:/UserName/Documents"]
        },
        "weather": {
            "command": "C:/Program Files/my-mcp/weather.exe"
        }
    }
}

Field	Required	Type	Description
command	Yes	String	Absolute path to the executable to launch.
args	No	Array of strings	Arguments passed to the executable.

Step 4: Verify tool availability

If the configuration file is present, the service connects to the MCP servers it lists and forwards their tools. Forwarded tools appear when the agent lists its available tools.

Step 5: Test the configuration

To confirm that tool forwarding works, run the mcpforwardingtester script. You can find it in the sample-code-for-workspaces-agent-access repository on GitHub. The script tests the MCP setup on your WorkSpace. It reports which tools are ready and flags any issues.

Note

Both IAM access and the service setting must be enabled for tool forwarding to work. IAM permissions do not override the service setting.

MCP tool forwarding considerations

Note the following considerations when you configure MCP tool forwarding:

• Transport is standard I/O (stdio) only. Each entry must launch a process that speaks MCP over its standard input and output. Remote HTTP or SSE MCP endpoints are not supported. To use a remote endpoint, wrap it in a local stdio server.

• Only command and args are supported. There is no field for environment variables or working directory. Each server inherits the environment of the streaming session and runs as the session user. Use absolute paths for command and for any path arguments.

• On Windows instances, use forward slashes in paths. For example, use C:/Program Files/my-mcp/server.exe. JSON treats the backslash as an escape character, so a Windows-style path written with single backslashes is invalid. Windows accepts forward slashes for absolute paths, which avoids the need to escape every separator as \\.

How forwarded tools appear to the agent

To prevent collisions between servers, the MCP server renames each forwarded tool in the agent's tool list using the following pattern:

forwarded___server-name___original-tool-name

The server-name is the key from your configuration file. For example, a get_forecast tool from the weather server is listed as forwarded___weather___get_forecast. When the agent calls the forwarded name, the MCP server routes the request to the original tool on the owning server. Agent code that matches on tool names must expect this prefix.

IAM permissions for tool forwarding

The IAM action for calling forwarded tools is CallForwardedTool. To limit access to specific stacks, use the StackArn condition key:

{
  "Effect": "Allow",
  "Action": ["agentaccess-mcp:InvokeMcp", "agentaccess-mcp:CallForwardedTool"],
  "Resource": "*",
  "Condition": {
    "ArnLike": {
      "agentaccess-mcp:StackArn": "arn:aws:appstream:region:account-id:stack/stack-name"
    }
  }
}

Image builder sessions use the ImageBuilderArn condition key instead of StackArn. To allow access only to specific image builders, use the ImageBuilderArn condition key:

{
  "Effect": "Allow",
  "Action": ["agentaccess-mcp:InvokeMcp", "agentaccess-mcp:CallForwardedTool"],
  "Resource": "*",
  "Condition": {
    "ArnEquals": {
      "agentaccess-mcp:ImageBuilderArn": "arn:aws:appstream:region:account-id:image-builder/image-builder-name"
    }
  }
}