localcore-gateway 0.1.0

Local, faithful-enough reimplementation of AWS Bedrock AgentCore Gateway, with a pluggable local Lambda backend.

localcore-gateway

A local, faithful-enough reimplementation of AWS Bedrock AgentCore Gateway, with a pluggable local Lambda backend. Develop and test agent ↔ gateway ↔ Lambda integrations entirely on your machine, then point the same MCP client at the real AWS gateway with no code changes.

There is no official local emulator for AgentCore Gateway (AWS's agentcore dev is for the Runtime, not the Gateway). This fills that gap.

0.x — unstable. The CLI flags and config schema may change between minor releases until 1.0. Pin a version if you depend on it.

What it reproduces

• MCP Streamable-HTTP at /mcp — the same wire surface as the real gateway (built on the FastMCP 3.x server; no hand-rolled JSON-RPC).
• Target aggregation — every (target, tool) is exposed as one MCP tool named target___tool (AgentCore's triple-underscore convention).
• AgentCore Lambda contract — the tool arguments are passed as the Lambda event; the tool identity is delivered via context.client_context.custom['bedrockAgentCoreToolName']; the Lambda's return value becomes the tool result.

Local Lambda backends

backend	Docker	fidelity	use it for
native	no	one subprocess per target (real process isolation — monorepo-safe), faithful event/context, error envelope, CloudWatch-style logs, hot reload, hard timeout	the fast dev loop
sam	yes	the real AWS Lambda Linux runtime via sam local start-lambda	full Linux-runtime fidelity check before AWS

Documentation

• Architecture — request flow, AgentCore contract mapping, component map
• Configuration reference — every config field
• Writing Lambda handlers — the handler contract, multi-tool, errors, logs, native vs sam
• CLI reference — serve / dev / tools / invoke
• Connecting agents — point an MCP client at it; promote to real AWS

Quick start

uv sync
uv run lcgw tools  -c examples/config.yaml          # show the tool catalog
uv run lcgw invoke -c examples/config.yaml demo___add --data '{"a":2,"b":40}'
uv run lcgw serve  -c examples/config.yaml           # MCP at http://127.0.0.1:8080/mcp
uv run lcgw dev    -c examples/config.yaml           # same, with hot reload

Point any MCP client at http://127.0.0.1:8080/mcp.

Using the sam backend

Run sam local start-lambda in your SAM project, then set in the target:

lambda:
  backend: sam
  sam_endpoint: http://127.0.0.1:3001
  sam_function: DemoFunction

Configuration

See examples/config.yaml. A target declares a Lambda (backend, handler/sam_function, memory_mb, timeout_sec, env) and the tools it backs (each with an explicit JSON Schema). One Lambda can back many tools; the handler branches on bedrockAgentCoreToolName.

Tests

uv run pytest

Known limitations

• native runs your handler in a subprocess but is not a security sandbox (no filesystem/network jail) — only point it at trusted code.
• native serializes invokes per target (one warm execution environment); it does not model Lambda's concurrent-environment scaling.
• sam per-invoke logs appear in the sam local console (out-of-band for the Invoke API).
• AgentCore's builtin semantic tool search (x_amz_bedrock_agentcore_search) is not implemented (intentionally omitted).
• Target types beyond Lambda (OpenAPI, MCP passthrough, Smithy) are not yet implemented.

License

Apache License 2.0. See NOTICE for attribution and the trademark disclaimer below.

Trademarks & disclaimer

This is an unofficial, community project. It is not affiliated with, endorsed by, or sponsored by Amazon Web Services, Inc. or its affiliates.

"AWS", "Amazon Web Services", "Amazon Bedrock", "Amazon Bedrock AgentCore", and "AWS Lambda" are trademarks of Amazon.com, Inc. or its affiliates. They are used here only nominatively, to accurately describe the AWS service this project interoperates with / reimplements locally. No AWS trademark, logo, or trade dress is used as the name or branding of this project.