feat(templates): support mcp python runtimes

[Hweinstock]

Problem

We're missing support for deploying mcp servers onto runtimes.

Solution

• wire up --protocol flag to the scaffolding flows in add and create.
• add a template entry corresponding to the strands mcp code from mainline.
• promote protocol as a key to the templates.

Verification.

> agentocre project create --name mcpTest --template py-mcp
...
> cd mcpTest
...
>  cat agentcore/agentcore.json | jq '.runtimes'
[
  {
    "name": "mcp_server",
    "build": "CodeZip",
    "entrypoint": "main.py",
    "codeLocation": "app/mcp_server",
    "runtimeVersion": "PYTHON_3_14",
    "protocol": "MCP"
  }
]
> agentcore project dev --mode headless --agent mcp_server
OTEL collector listening on port 34347; traces persist to [..]
[mcp_server] Starting development server
[mcp_server] [..]: IncompleteFieldDefinitionWarning: Field 'lifespan' has an incomplete definition: its annotation contains an unresolved forward reference, so settings sources may fail to correctly resolve its value. Call `model_rebuild()` on the model where the field is defined, once all the referenced types are defined.
[mcp_server]   warnings.warn(
[mcp_server] INFO:     Started server process [848144]
[mcp_server] INFO:     Waiting for application startup.
[mcp_server] StreamableHTTP session manager started
[mcp_server] INFO:     Application startup complete.
[mcp_server] INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
[mcp_server] INFO:     127.0.0.1:35250 - "POST /mcp HTTP/1.1" 200 OK
[mcp_server] Processing request of type CallToolRequest
[mcp_server] Terminating session: None
[mcp_server] INFO:     127.0.0.1:46980 - "POST /mcp HTTP/1.1" 200 OK
[mcp_server] Processing request of type ListToolsRequest
[mcp_server] Terminating session: None
^CShutting down…
[mcp_server] INFO:     Shutting down
[mcp_server] INFO:     Waiting for application shutdown.
[mcp_server] StreamableHTTP session manager shutting down
[mcp_server] INFO:     Application shutdown complete.
[mcp_server] INFO:     Finished server process [848144]

[ seperate terminal ] 
> curl -sS -X POST http://127.0.0.1:8000/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"add_numbers","arguments":{"a":21,"b":21}}}'
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"42"}],"structuredContent":{"result":42},"isError":false}}


> curl -sS -X POST http://127.0.0.1:8000/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add_numbers","description":"Add two numbers together","inputSchema":{"properties":{"a":{"title":"A","type":"integer"},"b":{"title":"B","type":"integer"}},"required":["a","b"],"title":"add_numbersArguments","type":"object"},"outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},"required":["result"],"title":"add_numbersOutput","type":"object"}},{"name":"multiply_numbers","description":"Multiply two numbers together","inputSchema":{"properties":{"a":{"title":"A","type":"integer"},"b":{"title":"B","type":"integer"}},"required":["a","b"],"title":"multiply_numbersArguments","type":"object"},"outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},"required":["result"],"title":"multiply_numbersOutput","type":"object"}},{"name":"greet_user","description":"Greet a user by name","inputSchema":{"properties":{"name":{"title":"Name","type":"string"}},"required":["name"],"title":"greet_userArguments","type":"object"},"outputSchema":{"properties":{"result":{"title":"Result","type":"string"}},"required":["result"],"title":"greet_userOutput","type":"object"}}]}}

[ back to original] 
> agentcore project deploy 
Created default deployment target: account [..], region us-east-1 (agentcore/aws-targets.json)
Verifying AWS account [..]
Synthesizing CloudFormation templates
Deploying AgentCore-mcpTest-default
Deployed project 'mcpTest' to target 'default'
ApplicationAgentMcpServerRoleArnOutput147F09F8: arn:aws:iam::[..]:role/AgentCore-mcpTest-default-ApplicationAgentMcpServer-kMegwLac6LLF
ApplicationAgentMcpServerRuntimeArnOutputCE3E0A42: arn:aws:bedrock-agentcore:us-east-1:[..]:runtime/mcpTest_mcp_server-B8P5JgHOQM
ApplicationAgentMcpServerRuntimeIdOutputE4E4FC7B: mcpTest_mcp_server-[..]
StackNameOutput: AgentCore-mcpTest-default

> aws bedrock-agentcore invoke-agent-runtime --region us-east-1 \
    --agent-runtime-arn arn:aws:bedrock-agentcore:us-east-1:[..]:runtime/mcpTest_mcp_server-B8P5JgHOQM \
    --content-type application/json --accept 'application/json, text/event-stream' \
    --cli-binary-format raw-in-base64-out \
    --payload '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
    /dev/stdout
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[{"name":"add_numbers","description":"Add two numbers together","inputSchema":{"properties":{"a":{"title":"A","type":"integer"},"b":{"title":"B","type":"integer"}},"required":["a","b"],"title":"add_numbersArguments","type":"object"},"outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},"required":["result"],"title":"add_numbersOutput","type":"object"}},{"name":"multiply_numbers","description":"Multiply two numbers together","inputSchema":{"properties":{"a":{"title":"A","type":"integer"},"b":{"title":"B","type":"integer"}},"required":["a","b"],"title":"multiply_numbersArguments","type":"object"},"outputSchema":{"properties":{"result":{"title":"Result","type":"integer"}},"required":["result"],"title":"multiply_numbersOutput","type":"object"}},{"name":"greet_user","description":"Greet a user by name","inputSchema":{"properties":{"name":{"title":"Name","type":"string"}},"required":["name"],"title":"greet_userArguments","type":"object"},"outputSchema":{"properties":{"result":{"title":"Result","type":"string"}},"required":["result"],"title":"greet_userOutput","type":"object"}}]}}

{
    "runtimeSessionId": "0827ecdd-c68a-4396-b9fe-97ef8735c258",
    "mcpSessionId": "0827ecdd-c68a-4396-b9fe-97ef8735c258",
    "contentType": "text/event-stream",
    "statusCode": 200
}

had an agent verify the same flow for container-based.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.25%. Comparing base (d304147) to head (c32e7fb).

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2155      +/-   ##
============================================
+ Coverage     97.22%   97.25%   +0.02%     
============================================
  Files           507      507              
  Lines         33809    33881      +72     
============================================
+ Hits          32872    32951      +79     
+ Misses          937      930       -7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Changes requested

Mostly clean, but there's one inconsistency worth fixing before merging.

protocol isn't treated as a scaffolding flag in add runtime

src/handlers/project/create/index.ts (lines 230–240) correctly adds "protocol" to scaffoldingChoiceFlags, so agentcore create --name x --protocol MCP engages the custom-scaffold path and Zod validates that language/framework are present.

src/handlers/project/add/runtime/index.ts (lines 129–137) does not include "protocol" in scaffoldingFlags. As a result, agentcore add runtime --name my_agent --protocol MCP (no other scaffolding flags) computes isCustom = false, falls through to the resolveRuntimeTemplateShortcut("hello-world-python", { runtimeName }) default, and produces a spec where:

• scaffoldRuntimeInput.protocol is undefined → files scaffolded from hello-world-python (HTTP-only Python template)
• runtimeInput.protocol = "MCP" (from line 224) → spec.runtimes[0].protocol = "MCP"

The user ends up with an MCP-declared runtime backed by HTTP hello-world code, with no error surfaced. Now that MCP is a first-class scaffolding choice, this silent mismatch is worth fixing.

Fix options (pick one):

1. Add "protocol" to the scaffoldingFlags array in add/runtime/index.ts so --protocol alone drives isCustom = true; the existing ScaffoldRuntimeInputSchema.safeParse will then reject missing language/framework with a clear error, matching create.
2. Explicitly reject --protocol without --template/--framework/--language in add/runtime/index.ts with an InputValidationError that names the required companion flags.

A regression test in src/handlers/project/add/runtime/index.test.ts covering --protocol MCP alone (in the rejection block) would lock this in.

Nits (non-blocking, no action required)

• The strands-py-mcp shortcut sets framework: "strands" even though pyproject.toml doesn't pull in strands-agents — the shortcut key drives resolver routing rather than declaring an actual dependency, which is fine, but the naming is a little misleading. Not a blocker.
• strands-py-mcp still allows --protocol HTTP as an override, which would route to the strands-http-python template but keep the mcp_server runtime name from the shortcut. Consider constraining overrides for template presets where the protocol is intrinsic (again, not a blocker).

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[Hweinstock]

Addressed the harness reviewer comments by keying the templates by protocol, and renaming to py-mcp.