Bug: AWS Marketplace deployment missing protocolConfiguration.serverProtocol=MCP — all invocations silently fail

[ryan-niemes-helix]

Bug: AWS Marketplace deployment missing protocolConfiguration.serverProtocol=MCP — all invocations silently fail (502 / timeout)

Summary

When the Falcon MCP Server runtime is deployed via the AWS Marketplace listing to Amazon Bedrock AgentCore, the resulting AgentCore Runtime is created without the protocolConfiguration.serverProtocol field set to MCP. This causes all invocations to silently fail: the container starts correctly, but no requests ever reach it.

There is a second related issue for anyone connecting via an AgentCore Gateway target: some Falcon tool names are long enough that they will exceed Bedrock's 64-character tool name limit depending on how the Gateway target is named.

Both issues are confirmed and fixed — details below.

---

Issue 1: Missing protocolConfiguration.serverProtocol=MCP

Environment

• Deployment method: AWS Marketplace → Amazon Bedrock AgentCore Runtime
• falcon-mcp version: 0.8.0
• Region: us-east-1

Symptoms

• FALCON_MCP_HOST=0.0.0.0, FALCON_MCP_PORT=8000, FALCON_MCP_TRANSPORT=streamable-http, FALCON_MCP_STATELESS_HTTP=true are all set correctly in the runtime environment
• Container starts successfully: uvicorn binds to 0.0.0.0:8000, 47 tools initialized
• All direct invocations return either a 502 error or time out after 30 seconds
• CloudWatch logs confirm zero HTTP requests ever reach uvicorn — only the internal sidecar health check (127.0.0.1 - "POST /mcp HTTP/1.1" 200 OK) appears
• Any AgentCore Gateway target pointing at this runtime fails with: "Did not observe any item or terminal signal within 20000ms in 'map'"

Root cause

The Amazon Bedrock AgentCore Runtime sidecar uses protocolConfiguration.serverProtocol to determine which container port/path to proxy to:

Protocol	Port	Path
HTTP (default)	8080	/invocations
MCP	8000	/mcp

When protocolConfiguration is absent, the sidecar defaults to HTTP (port 8080). Since the Falcon MCP container only listens on port 8000, every request fails at the sidecar before reaching the application. Confirmed via get_agent_runtime() — no protocolConfiguration field present in Marketplace-deployed runtimes.

Fix (confirmed working)

After subscribing via the Marketplace, patch the runtime:

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-east-1')
runtime = client.get_agent_runtime(agentRuntimeId='<YOUR_RUNTIME_ID>')

client.update_agent_runtime(
    agentRuntimeId='<YOUR_RUNTIME_ID>',
    roleArn=runtime['roleArn'],
    networkConfiguration=runtime['networkConfiguration'],
    protocolConfiguration={'serverProtocol': 'MCP'},
    agentRuntimeArtifact=runtime['agentRuntimeArtifact'],
    environmentVariables=runtime['environmentVariables'],
)

After updating, recreate any Gateway targets that entered FAILED state.

Expected fix

The Marketplace deployment should include protocolConfiguration.serverProtocol = "MCP" at runtime creation time.

---

Issue 2: Tool names exceed Bedrock's 64-char limit when used via AgentCore Gateway

Context

When connecting Falcon MCP via an AgentCore Gateway target, the Gateway prefixes all tool names as gateway_{target-name}___. Bedrock's ConverseStream API enforces a 64-character hard limit on tool spec names — violations throw a ValidationException that silently hangs every agent request.

Affected tools

With a Gateway target named falcon-mcp-target (prefix = gateway_falcon-mcp-target___ = 27 chars, leaving 37 chars for tool names), 9 Falcon tools exceed the limit:

Tool name	Length	Full prefixed length
falcon_images_vulnerabilities_fql_filter_guide	46	73
falcon_kubernetes_containers_fql_filter_guide	45	72
falcon_serverless_vulnerabilities_fql_guide	43	70
falcon_search_scheduled_reports_fql_guide	41	68
falcon_search_report_executions_fql_guide	41	68
falcon_search_unmanaged_assets_fql_guide	40	67
falcon_search_vulnerabilities_fql_guide	39	66
falcon_search_ioa_rule_groups_fql_guide	39	66
falcon_search_firewall_rules_fql_guide	38	65

Workaround

Name the Gateway target falcon (prefix = gateway_falcon___ = 17 chars, leaving 47 chars). The longest tool (falcon_images_vulnerabilities_fql_filter_guide = 46 chars) results in a 63-char total — all 47 tools fit.

Suggested fix options

1. Documentation: Add a note to the AgentCore deployment docs recommending the Gateway target be named falcon (or shorter)
2. Rename long tools: The _fql_filter_guide / _fql_guide suffix pattern appears across several tools — shortening these would give users more flexibility in naming their Gateway targets