localcore-gateway

English | 日本語

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), including the modern (May 2026+) behavior: stateful sessions (Mcp-Session-Id) and SSE-streamed responses. ⚠️ This is the new default — server: { stateless: true } restores the previous buffered-JSON mode.
• Interactive passthrough (MCP targets) — mid-call progress and logging notifications stream through to the caller as they're produced, and downstream elicitation (form mode) and sampling requests are relayed to your client and answered back down — the same passthroughs the real gateway documents.
• 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).
• Smithy targets — a Smithy 2.0 JSON AST model's operations become MCP tools (aws.protocols#restJson1 only and 10 MB max, same as the real gateway); tool name = the operation's shape name; restJson1 HTTP bindings (httpLabel/httpQuery/httpHeader/httpPayload) drive the request; auth is none/apikey/bearer for local servers or SigV4 for real AWS services. This completes the real gateway's target-type matrix.
• MCP-passthrough targets — another MCP server's whole catalog is proxied: tools, prompts (target___prompt, AWS's documented naming), and resources (URIs as-is; shared URIs routed by resource_priority, the AgentCore resourcePriority analog), with prompts/get and resources/read forwarded live. Streamable HTTP is the AgentCore-faithful mode; a local stdio command mode is also available as a local-only convenience (no AWS analog).
• Target re-sync — lcgw sync is the SynchronizeGatewayTargets analog: MCP targets re-discover their upstream catalog on a running gateway, no restart (synchronous, unlike AWS's async 202-style API). Plus a dev-loop extra with no AWS analog: lcgw tail streams every tool invocation live.

targets:
  - type: mcp
    name: mytools
    url: http://127.0.0.1:9000/mcp
    auth: { type: bearer, value: "${TOKEN}" }   # expanded from the environment

Hybrid debugging (mix in real AWS)

With the aws extra installed, the local gateway can mix real AWS resources in next to local ones — iterate on one tool locally while the rest of your production toolset stays real:

• type: aws-gateway — proxy a deployed AgentCore Gateway: its tools pass through with their remoteTarget___tool names verbatim (unprefixed); auth is bearer (OAuth/JWT) or SigV4 (IAM). No AWS analog — purely a hybrid-workflow tool.
• lambda.backend: aws — a third Lambda backend: the tool schema is local, the handler is the real deployed function (same AgentCore ClientContext contract, CloudWatch log tail included; retries disabled so a side-effecting invoke is never silently doubled).

See examples/hybrid_config.yaml and the configuration reference.

Testing & contracts (local-only extras)

• Mock targets (type: mock) — tools declared entirely in config with canned responses/errors, so the agent can be developed before the tools exist. No AWS analog.
• Contract checks (server.contract_checks: warn|error) — validate tool arguments and results against the declared JSON Schemas at the gateway, catching schema/handler drift before deploying. Off by default (the real gateway doesn't validate).
• localcore_gateway.testing — public pytest helpers: serve_gateway spins up the full gateway on an ephemeral port, call_tool makes one-shot assertions. See Testing your handlers.
• Config validation — lcgw schema emits the config file's JSON Schema (wire it to your editor via yaml-language-server); lcgw preflight checks a config against real-AgentCore deploy constraints (name patterns, quotas, local-only constructs) before you deploy. See the CLI reference.

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
aws	no	the real deployed function (requires the aws extra + credentials)	hybrid debugging against production-like resources

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
• Testing your handlers — localcore_gateway.testing, mock targets, contract checks in pytest
• CLI reference — serve / dev / tools / invoke / sync / tail / schema / preflight
• 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

For the real-AWS passthrough features (type: aws-gateway, lambda.backend: aws), install the aws extra:

uv tool install 'localcore-gateway[aws]'   # or: pip install 'localcore-gateway[aws]'

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
lcgw tail   -c gateway.yaml            # live per-invocation stream (running gateway)
lcgw sync   -c gateway.yaml            # re-sync MCP targets (running gateway)

Point any MCP client at http://127.0.0.1:8080/mcp. Richer examples (multi target, math_handlers.py, Strands agent, MCP-passthrough via mcp_config.yaml) 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).
• All four real target types are implemented — Lambda, OpenAPI, Smithy, and MCP-passthrough — plus the local-only AWS-gateway passthrough and mock targets. Outbound auth (OpenAPI and MCP-passthrough alike) covers static API key (header/query) and bearer; OAuth 2LO is out of scope. Smithy accepts any restJson1 model locally (AWS restricts custom models to AWS services) and requires base_url (endpoint rule sets are not implemented).
• The hybrid features (type: aws-gateway, lambda.backend: aws) require the aws extra and real AWS credentials, and are subject to AWS-side behavior (cold starts, IAM, quotas) — nothing local emulates them.

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.