Agent Middleware MCP server
Commit Nov 12, 2026Provides a secure gateway for agent tool calls using signed permits, idempotency keys, and verifiable offline receipts.
Also known as agentmiddleware/agent-middleware
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- Apache-2.0
What is Agent Middleware MCP?
Agent Middleware provides a secure gateway for agent tool calls using signed permits, idempotency keys, and verifiable offline receipts.
Summary generated from the project's README
About Agent Middleware MCP server
Securing high-stakes agent actions like refunds, payouts, or deployments is the primary function of agent-middleware. It acts as a gateway positioned in front of risky tools to ensure every invocation follows strict governance. Developers can use this as a local gateway via a Makefile or connect an MCP client to a hosted endpoint using an API key passed in the X-API-Key header.
The system relies on several core concepts to maintain control. It uses permits, which are signed grants that define specific tools, budgets, and expiration times, and idempotency keys to prevent duplicate requests. Every successful call generates a signed receipt containing hashes of the request and response, allowing for offline verification. This setup is designed for developers who need to manage consequential tool calls through a structured protocol rather than direct execution.
What you can do with it
- 1Preventing duplicate financial transactionsEnsure a payout or refund is only processed once even if the agent retries the request.
- 2Verifying tool outcomes offlineCheck the validity of a tool call's result using a signed record without needing a live connection.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
AMW_API_KEYAMW_WALLET_ID
| Name | Description | |
|---|---|---|
| AMW_API_KEY | — | |
| AMW_WALLET_ID | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableagentmiddleware/agent-middleware is public and reachablegithub.com/agentmiddleware/agent-middleware ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/agentmiddleware/agent-middleware ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAgent Middleware
Agent Middleware is a gateway you put in front of an agent's risky tools (refunds, payouts, deploys) so each action needs a signed permit, runs at most once per request key, and leaves a signed receipt anyone can check offline.
Status: Pre revenue, pre release, solo maintained. There are no paying customers or production deployments to point to. We are looking for design partners with one real consequential tool. Install from source; nothing is published to PyPI or npm.
Try it in 3 minutes
Use the hosted demo. Get a demo key at the demo key page. The example also needs the associated wallet ID.
Connecting an MCP client to the hosted endpoint https://api.agentmiddleware.dev/mcp? Get an API key and send it as the X-API-Key header.
git clone https://github.com/agentmiddleware/amw-demo.git
cd amw-demo
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
export AMW_API_KEY='<your key>'
export AMW_WALLET_ID='<your wallet id>'
python examples/permit_echo_retry.py
The example creates a permit, calls the reference echo tool, retries with the same key, and checks the receipt offline.
Run it locally
Use the gateway Makefile to start a local gateway. QUICKSTART.md has the full walk through.
git clone https://github.com/agentmiddleware/agent-middleware
cd agent-middleware/gateway
make quickstart
Concepts
- Permit: A signed grant that limits an agent to specified tools, a budget, and an expiry.
- Call: A governed MCP tool invocation under a permit.
- Request key: The
Idempotency-Keyheader that identifies a request for retry handling. - Receipt: A signed record of a call's outcome and hashes of its request and response, with a debit link when applicable.
- Credits: Internal metering units, not money.
Guarantees and limits
- a retry with the same key returns the original receipt instead of dispatching again
- a new key is a new request
- Reusing a key with a different request fails with a conflict before dispatch.
- A
delivery_uncertainreceipt means no trustworthy answer came back. The debit is kept, and the operator must reconcile with the downstream tool. The gateway does not resend automatically. - The gateway limits dispatch and debit per key, but remote effects depend on the tool honoring the forwarded key. A receipt signs request and response hashes, not raw tool content, and cannot prove a remote effect happened. This is not exactly once.
Read Security Limitations before relying on the gateway for a consequential action.
Repo map
This repository holds the reference gateway, protocol spec, SDKs,
integrations, and design-partner pilot loop (start with
QUICKSTART.md). The separate agent-middleware-api
repository is outside this checkout; partner evaluation guidance is here.
| Path | What it contains |
|---|---|
| gateway/ | Gateway implementation and local Makefile |
| sdk/ | Python and TypeScript client and verification code |
| verifier/ | Offline verification guide and vector checker |
| spec/ | Draft permit, receipt, and key formats |
| integrations/ | Framework wrappers and adapters |
| examples/ | Runnable examples and MCP client config |
| amw-demo | Hosted demo client and receipt verifier |
| amw-paypal-agent-demo | PayPal agent demo |
Apache 2.0 (gateway is Fair Source, FSL-1.1)
Agent Middleware MCP questions
What happens if I retry a request with the same key?
A retry using the same key will return the original receipt instead of dispatching the action again.
Can the gateway prove that a remote effect actually happened?
No, the receipt signs request and response hashes rather than raw tool content, so it cannot prove a remote effect occurred.
What is a 'delivery_uncertain' receipt?
This status means no trustworthy answer was returned; the debit is kept and the operator must manually reconcile with the downstream tool.