{"_id":"aws-sigv4-mcp-proxy","_rev":"2-a51e2e32bbdb55cd53b78f4f4b4263fd","name":"aws-sigv4-mcp-proxy","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.1":{"name":"aws-sigv4-mcp-proxy","version":"0.1.1","keywords":["mcp","model-context-protocol","aws","sigv4","bedrock-agentcore","proxy","iam"],"author":{"name":"steel8rat"},"license":"MIT","_id":"aws-sigv4-mcp-proxy@0.1.1","maintainers":[{"name":"steel8rat","email":"steel8rat@gmail.com"}],"homepage":"https://github.com/steel8rat/aws-sigv4-mcp-proxy#readme","bugs":{"url":"https://github.com/steel8rat/aws-sigv4-mcp-proxy/issues"},"bin":{"aws-sigv4-mcp-proxy":"dist/cli.js"},"dist":{"shasum":"c25199e48ab5dab041e4d8103e7073d619c128fb","tarball":"https://registry.npmjs.org/aws-sigv4-mcp-proxy/-/aws-sigv4-mcp-proxy-0.1.1.tgz","fileCount":54,"integrity":"sha512-jA7FwcNwZbS83C7WUMiDHol8vVckwwSrQotFVxdO/OryAo79acvlWtDsXmeC+u0OcXXS99sEhXllDKj5Ksr/XA==","signatures":[{"sig":"MEUCIQCdZL2L/A/9S+4T/8cFXsNfsz7EGwv8KLgBIwyeOEG8jwIgOIfl6Okvt7IjvffKL6+fRNfCWmv2gWLCaromc+L2SG4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":118892},"type":"module","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"23e9891f5d48a7cc0e2af020fed38d3f082cf0b2","scripts":{"test":"node --test \"tests/*.test.ts\"","build":"tsc -p tsconfig.json && chmod +x dist/cli.js","clean":"rm -rf dist","pretest":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"steel8rat","email":"steel8rat@gmail.com"},"repository":{"url":"git+https://github.com/steel8rat/aws-sigv4-mcp-proxy.git","type":"git"},"_npmVersion":"11.16.0","description":"Bridge plain-HTTP or stdio MCP clients to AWS SigV4-gated MCP endpoints (Bedrock AgentCore, API Gateway, Lambda Function URLs).","directories":{},"_nodeVersion":"24.18.0","dependencies":{"@smithy/types":"^3.7.2","@smithy/signature-v4":"^4.2.4","@aws-crypto/sha256-js":"^5.2.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^20.19.0","@aws-sdk/credential-provider-node":"^3.0.0"},"peerDependencies":{"@aws-sdk/credential-provider-node":"^3.0.0"},"peerDependenciesMeta":{"@aws-sdk/credential-provider-node":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/aws-sigv4-mcp-proxy_0.1.1_1788202845811_0.7261681424867978","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"_id":"aws-sigv4-mcp-proxy@0.2.0","bin":{"aws-sigv4-mcp-proxy":"dist/cli.js"},"bugs":{"url":"https://github.com/steel8rat/aws-sigv4-mcp-proxy/issues"},"dist":{"shasum":"9b0e67b7a5d597bea944b16acd9fa299fead0b35","tarball":"https://registry.npmjs.org/aws-sigv4-mcp-proxy/-/aws-sigv4-mcp-proxy-0.2.0.tgz","fileCount":59,"integrity":"sha512-s3bwW85Z/i3kpxwr2YqI8kh91BMWRl7Jk7k6OfZwBq4HGm7fC3JRzAbTQ8iv2L4aUjowS5phHQpSNtACoLti/Q==","signatures":[{"sig":"MEYCIQDXFgCeVpTW1apPf7nyohxrUg/Ajq9ymCTZsS23fT9nagIhAP2Se7ucflcpV6sjprKdspsWf49iuA8SReJFuR8+e+3G","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBwBlpSbYNa91EjFR4kVvyHrIdRBOdDbB2V+qZplOyHrAiEAlwQZM4oqJtmbe50jUR1fYJ0vH40UhQW9WmUsqj2XTKM="}],"unpackedSize":160416},"name":"aws-sigv4-mcp-proxy","type":"module","author":{"name":"steel8rat"},"engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"b2c23613c05dd443795a99a4e8b76d44ecef767c","license":"MIT","scripts":{"test":"node --test \"tests/*.test.ts\"","build":"tsc -p tsconfig.json && chmod +x dist/cli.js","clean":"rm -rf dist","pretest":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","prepublishOnly":"npm run clean && npm run build"},"version":"0.2.0","_npmUser":{"name":"steel8rat","email":"steel8rat@gmail.com"},"homepage":"https://github.com/steel8rat/aws-sigv4-mcp-proxy#readme","keywords":["mcp","model-context-protocol","aws","sigv4","bedrock-agentcore","proxy","iam"],"repository":{"url":"git+https://github.com/steel8rat/aws-sigv4-mcp-proxy.git","type":"git"},"_npmVersion":"11.16.0","description":"Bridge plain-HTTP or stdio MCP clients to AWS SigV4-gated MCP endpoints (Bedrock AgentCore, API Gateway, Lambda Function URLs).","directories":{},"maintainers":[{"name":"steel8rat","email":"steel8rat@gmail.com"}],"_nodeVersion":"24.18.0","dependencies":{"@smithy/types":"^3.7.2","@smithy/signature-v4":"^4.2.4","@aws-crypto/sha256-js":"^5.2.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^20.19.0","@aws-sdk/credential-provider-node":"^3.0.0"},"peerDependencies":{"@aws-sdk/credential-provider-node":"^3.0.0"},"peerDependenciesMeta":{"@aws-sdk/credential-provider-node":{"optional":true}},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aws-sigv4-mcp-proxy_0.2.0_1790114129971_0.6766671783293421"}}},"time":{"created":"2026-08-31T19:00:45.719Z","modified":"2026-09-22T21:55:30.254Z","0.1.1":"2026-08-31T19:00:45.941Z","0.2.0":"2026-09-22T21:55:30.086Z"},"bugs":{"url":"https://github.com/steel8rat/aws-sigv4-mcp-proxy/issues"},"author":{"name":"steel8rat"},"license":"MIT","homepage":"https://github.com/steel8rat/aws-sigv4-mcp-proxy#readme","keywords":["mcp","model-context-protocol","aws","sigv4","bedrock-agentcore","proxy","iam"],"repository":{"url":"git+https://github.com/steel8rat/aws-sigv4-mcp-proxy.git","type":"git"},"description":"Bridge plain-HTTP or stdio MCP clients to AWS SigV4-gated MCP endpoints (Bedrock AgentCore, API Gateway, Lambda Function URLs).","maintainers":[{"name":"steel8rat","email":"steel8rat@gmail.com"}],"readme":"# aws-sigv4-mcp-proxy\n\nBridge a plain-HTTP or stdio [MCP](https://modelcontextprotocol.io) client to an\n**AWS SigV4-gated MCP endpoint** — Amazon Bedrock AgentCore runtimes, or any MCP\nserver behind API Gateway / a Lambda Function URL / IAM auth.\n\nMost MCP clients (Claude Desktop, Cursor, VS Code, Kiro, the GitHub Copilot SDK, …)\ncan only be pointed at a static URL with static headers, or launched as a\n`command` subprocess. None of them can compute a SigV4 signature per request, so\nthey cannot talk to an IAM-secured endpoint directly. This package sits in\nbetween:\n\n```\nMCP client  ──plain HTTP / stdio──▶  aws-sigv4-mcp-proxy  ──SigV4-signed HTTPS──▶  AWS\n```\n\nIt signs every forwarded request with SigV4 using whatever credentials the\nprocess already has (env vars, SSO cache, an EC2 / ECS / AgentCore execution\nrole — the standard AWS credential chain), so the client never has to know AWS\nauth exists.\n\nThis is a small, dependency-light TypeScript counterpart to AWS's Python\n[`mcp-proxy-for-aws`](https://github.com/aws/mcp-proxy-for-aws). It exists because\nembedding the Python tool (boto3 + botocore + uv) into a Node container adds\n~250&nbsp;MB; this package's runtime dependencies are the Smithy SigV4 signer and\na SHA-256 implementation (~6&nbsp;MB unpacked, no AWS SDK client).\n\n## Install\n\n```bash\nnpm install aws-sigv4-mcp-proxy\n```\n\nTo use the default AWS credential chain (recommended on ECS / Lambda / AgentCore),\nalso install the optional peer dependency:\n\n```bash\nnpm install @aws-sdk/credential-provider-node\n```\n\nRequires Node.js ≥ 20 (uses the global `fetch`).\n\n## CLI — stdio mode\n\nThe default mode reads newline-delimited JSON-RPC on stdin, signs and forwards\neach message over MCP Streamable HTTP, and writes responses (JSON or\n`text/event-stream`) back to stdout. This is how most MCP clients expect to launch\na server.\n\n```bash\n# Bedrock AgentCore runtime (service + region are inferred from the ARN)\naws-sigv4-mcp-proxy arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my_mcp-abcd1234\n\n# Any other SigV4-gated endpoint\naws-sigv4-mcp-proxy --url https://abc123.execute-api.us-east-1.amazonaws.com/prod/mcp \\\n  --service execute-api --region us-east-1\n```\n\nExample client config (`.mcp.json`, Claude Desktop, Cursor, VS Code — same shape):\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"my_remote_mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"aws-sigv4-mcp-proxy\",\n        \"arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my_mcp-abcd1234\"\n      ],\n      \"env\": { \"AWS_PROFILE\": \"my-sso-profile\", \"AWS_REGION\": \"us-east-1\" }\n    }\n  }\n}\n```\n\n## CLI — HTTP listener mode\n\n`--http` starts a local unauthenticated listener instead. Point a client that\nonly accepts a static URL at it.\n\n```bash\naws-sigv4-mcp-proxy --http --port 9100 \\\n  arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my_mcp-abcd1234\n# [aws-sigv4-mcp-proxy] listening on http://127.0.0.1:9100/mcp -> https://bedrock-agentcore...\n```\n\n```jsonc\n{ \"my_remote_mcp\": { \"type\": \"http\", \"url\": \"http://127.0.0.1:9100/mcp\" } }\n```\n\n### All flags\n\n| Flag | Description |\n| --- | --- |\n| `<url\\|runtime-arn>` | Positional target: a URL, or an `arn:…` AgentCore runtime ARN |\n| `--url` / `--runtime-arn` | Same as the positional, explicit form |\n| `--http` | Run a local HTTP listener instead of the stdio bridge |\n| `--service` | SigV4 service name (default `bedrock-agentcore` for an ARN; required with `--url`) |\n| `--region` | AWS region (default: parsed from the ARN, else `$AWS_REGION` / `$AWS_DEFAULT_REGION`) |\n| `--qualifier` | AgentCore runtime qualifier (default `DEFAULT`) |\n| `--protocol-version` | Initial `MCP-Protocol-Version` header (stdio mode; updated from the `initialize` result) |\n| `--no-server-stream` | Do not open a standalone GET SSE stream for server-initiated messages (stdio mode) |\n| `--retry-empty-response` | Replay a request answered with an empty HTTP 200, up to 3 attempts — see [Empty responses](#empty-responses) |\n| `--port` / `--host` / `--path` | HTTP listener bind settings (default `127.0.0.1`, ephemeral port, `/mcp`) |\n\n## Programmatic API\n\n### Generic core\n\n```ts\nimport { startSigV4Proxy } from \"aws-sigv4-mcp-proxy\";\n\nconst proxy = await startSigV4Proxy({\n  targetUrl: \"https://abc123.execute-api.us-east-1.amazonaws.com/prod/mcp\",\n  service: \"execute-api\",\n  region: \"us-east-1\",\n  // credentials?: static creds or a provider; omit for the default chain\n  port: 9100,            // optional; default: ephemeral\n});\n\nconsole.log(proxy.url); // http://127.0.0.1:9100/mcp\n// ... on shutdown:\nawait proxy.close();\n```\n\n```ts\nimport { startStdioProxy } from \"aws-sigv4-mcp-proxy\";\n\nconst proxy = await startStdioProxy({\n  targetUrl,\n  service: \"execute-api\",\n  region: \"us-east-1\",\n});\nawait proxy.done; // resolves when stdin ends and in-flight messages are flushed\n```\n\n### Bedrock AgentCore convenience layer\n\n```ts\nimport { startAgentCoreProxy, startAgentCoreStdioProxy, agentCoreInvocationUrl } from \"aws-sigv4-mcp-proxy\";\n\nconst proxy = await startAgentCoreProxy({\n  runtimeArn: process.env.MY_MCP_RUNTIME_ARN!, // region + service inferred\n  qualifier: \"DEFAULT\",                        // optional\n  port: 9100,                                  // optional\n});\n\nagentCoreInvocationUrl(runtimeArn);\n// https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations?qualifier=DEFAULT\n```\n\n## How the AgentCore invoke URL is derived\n\nThere is no published AWS REST reference for invoking an AgentCore runtime over\nsigned HTTP. The path shape here is reverse-engineered from AWS's own tooling —\nthe `agentcore` CLI's Smithy operation table (`InvokeAgentRuntime` →\n`POST /runtimes/{agentRuntimeArn}/invocations`) and its URL builder — and matches\nwhat the Python `mcp-proxy-for-aws` uses. AWS's tooling treats this endpoint as a\ngenuine MCP Streamable HTTP passthrough (raw JSON-RPC body, `Mcp-Session-Id` /\n`Mcp-Protocol-Version` headers), which is what this proxy relies on.\n\nIt has been verified end to end against a live runtime. Still: cross-check it if\nAWS publishes an official reference, and watch for it changing across `agentcore`\nCLI versions. Override the pieces you need with `region`, `qualifier`, and\n`dnsSuffix` (for non-standard partitions), or bypass the convenience layer\nentirely with `startSigV4Proxy` + your own `targetUrl`.\n\n## Design notes\n\n- **Single target per instance.** One proxy instance maps to exactly one upstream\n  endpoint. It does not route by path or header to multiple targets — run one\n  instance per target. This keeps signing, session handling and error mapping\n  unambiguous, and is deliberate; please don't re-litigate it without a concrete\n  need.\n- **Responses are streamed, not buffered.** `text/event-stream` responses (MCP's\n  mechanism for long-running calls and server notifications) are piped through\n  chunk by chunk in both modes.\n- **stdio session handling.** The bridge tracks `Mcp-Session-Id` from the first\n  response and the negotiated protocol version from the `initialize` result, and\n  attaches both to subsequent requests. After initialization it opens a standalone\n  `GET` SSE stream for server-initiated messages, disabling it silently if the\n  upstream answers `4xx`/`5xx` (e.g. `405` when the server has no such stream).\n- **Transport failures are JSON-RPC shaped.** An unreachable upstream or a non-2xx\n  response is returned to the client as\n  `{ \"jsonrpc\": \"2.0\", \"id\": <request id>, \"error\": { \"code\": -32001, \"message\": … } }`\n  rather than a bare HTTP failure.\n- **Empty responses are reported, not passed through.** See below.\n- **Header allowlist.** Request: `content-type`, `accept` (forced to\n  `application/json, text/event-stream` when missing or `*/*`), `mcp-session-id`,\n  `mcp-protocol-version`, `last-event-id`. Response: `content-type`,\n  `cache-control`, `mcp-session-id`, `mcp-protocol-version`, `www-authenticate`.\n  Both lists are overridable via `forwardRequestHeaders` / `forwardResponseHeaders`.\n\n## Empty responses\n\nAn upstream can answer a JSON-RPC request with HTTP 200 and an empty body. MCP\nclients then report a bare `Transport closed`, or — over stdio — wait forever.\nAgainst Bedrock AgentCore this is how a failed or not-yet-listening container\nsurfaces: the platform masks the container's error as an empty 200.\n\n**Reporting (always on).** When a request that is owed a response — a `POST` of a\nsingle JSON-RPC request with a `method` and an `id` — gets none, the proxy answers\nwith a JSON-RPC error instead of silence:\n\n```json\n{ \"jsonrpc\": \"2.0\", \"id\": 1, \"error\": { \"code\": -32603, \"message\": \"Upstream returned HTTP 200 with an empty body\" } }\n```\n\n- The HTTP status stays `200`, as JSON-RPC carries errors in the body. If the\n  upstream declared `text/event-stream`, the error is sent as one SSE `message`\n  event; otherwise as `application/json`.\n- \"Empty\" means no non-whitespace byte before the body ends. Only the leading\n  bytes are read to decide this; SSE bodies keep streaming.\n- In stdio mode, an SSE response that ends without a message answering the\n  request produces `-32603 \"Upstream stream ended without a response\"`.\n- Notifications, client responses, batches, `GET` streams and `DELETE` pass an\n  empty 200 through unchanged — for them it is legitimate.\n\n**Retry (off by default).** `retryEmptyResponse: true` (or\n`{ attempts, backoffMs }`, defaults 3 total attempts and 150ms; CLI\n`--retry-empty-response`) replays the identical signed request after an empty\n200, with exponential, fully jittered backoff, before falling back to the error\nabove. Each retry is logged through `onWarn`.\n\n> [!WARNING]\n> Retrying trades at-most-once for **at-least-once** execution. A container that\n> dies while writing its response has already run the tool, so a replay of a\n> write tool applies it twice. MCP has no idempotency key that could make the\n> replay safe (see SEP-1335 in `modelcontextprotocol/modelcontextprotocol`).\n> The retry also hides container faults that the error would have surfaced —\n> leave it off unless your tools are idempotent, and investigate the upstream\n> either way.\n\n### Limitations\n\n- SSE resumption via `Last-Event-ID` is passed through but the standalone\n  server-stream does not yet reconnect automatically on drop.\n- In HTTP mode, an SSE body is judged empty only by its bytes: a stream carrying\n  just keep-alive comments or events without a response is passed through, not\n  reported. (stdio mode parses the stream and does report it.)\n- The HTTP listener is unauthenticated; bind it to loopback (the default) and\n  treat it as a local-only shim.\n\n## Prior art\n\n| Package | Why it doesn't fit |\n| --- | --- |\n| [`aws/mcp-proxy-for-aws`](https://github.com/aws/mcp-proxy-for-aws) | Python only; boto3/botocore too heavy to embed in a Node container |\n| `mcp-proxy` (npm) | SSE ↔ stdio bridge, no AWS auth |\n| `mcp-remote` (npm) | OAuth-based remote MCP proxy, not SigV4 |\n| `@aws/bedrock-agentcore-sdk-typescript` | `RuntimeClient` only covers WebSocket/shell auth, no signed HTTP invoke |\n| [`aws-sigv4-fetch`](https://github.com/zirkelc/aws-signature-v4) | The right signing primitive, but not a proxy |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}