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.
• OpenAPI targets — a REST API's spec becomes MCP tools; the tool name is the operation's operationId verbatim (as the real gateway does, not a slugified form), spec-level security is ignored (auth configured out of band).

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

Install

uv tool install localcore-gateway      # or: pipx install localcore-gateway
uvx --from localcore-gateway lcgw --help   # one-off, no install

Quick start

A handler and a config (nothing else needed):

# handlers.py
def handler(event, context):
    return {"sum": event["a"] + event["b"]}

# gateway.yaml
targets:
  - type: lambda
    name: demo
    lambda: { backend: native, handler: handlers.handler }
    tools:
      - name: add
        inputSchema:
          type: object
          properties: { a: { type: number }, b: { type: number } }
          required: [a, b]

lcgw tools  -c gateway.yaml
lcgw invoke -c gateway.yaml demo___add --data '{"a":2,"b":40}'
lcgw serve  -c gateway.yaml            # MCP at http://127.0.0.1:8080/mcp
lcgw dev    -c gateway.yaml            # same, with hot reload

Point any MCP client at http://127.0.0.1:8080/mcp. Richer examples (multi target, math_handlers.py, Strands agent) are in examples/.

From source (development)

git clone https://github.com/tawAsh1/localcore-gateway && cd localcore-gateway
uv sync
uv run pytest
uv run lcgw serve -c examples/config.yaml

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.

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: Lambda and OpenAPI are implemented; MCP-passthrough and Smithy are not yet. OpenAPI outbound auth covers static API key (header/query) and bearer; OAuth 2LO is out of scope.

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.