AXG MCP server
Commit Nov 10, 2026Provides a deterministic policy engine that evaluates AI agent actions against declarative rules and issues signed RS256 Passports for verifiable execution.
Also known as pinheirodps/axg
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
What is AXG MCP?
AXG provides a deterministic policy engine that evaluates AI agent actions against declarative rules and issues signed RS256 Passports for verifiable execution.
Summary generated from the project's README
About AXG MCP server
Controlling AI agent actions through deterministic rules is what AXG enables for developers building autonomous systems. It acts as a policy engine that evaluates proposed actions like shell commands or tool calls against declarative rules to return decisions such as ALLOW, SUGGEST, CONFIRM, or BLOCK. This ensures that agents operate within strict safety boundaries without relying on a model to make the final decision.
Users can deploy the engine via Docker or embed it directly into Python or Node.js applications using the provided SDKs. The system requires an API key for authentication and can be integrated into MCP servers through a gateway proxy or specific tool verification commands. When an action is permitted, AXG issues an RS256 Passport, which is a signed JWT that binds the decision to the specific payload to prevent tampering during execution.
This engine is designed for auditability and security, featuring hash-chained audit logs and OpenTelemetry traces. It provides a framework-agnostic way to manage agent permissions, making it suitable for any orchestrator or backend service that needs verifiable execution control.
What you can do with it
- 1Implementing human-in-the-loop approvalsHigh-risk actions can be routed to a human for confirmation before the agent is allowed to proceed.
- 2Securing agent payloads with digital signaturesThe system uses signed Passports to ensure that the data being executed has not been altered after authorization.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
AXG_CLIENTSAXG_KEY
Automated checks
Ran Nov 14, 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 reachablepinheirodps/axg is public and reachablegithub.com/pinheirodps/axg ↗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-10github.com/pinheirodps/axg ↗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 GitHubAXG — Agent Execution Guard

Deterministic, auditable control over what AI agents are allowed to do.
AI suggests. AXG decides.
An agent proposes an action (write a record, run a shell command, call a tool). Before anything executes, AXG evaluates it against a declarative policy and answers ALLOW, SUGGEST, CONFIRM or BLOCK. An ALLOW comes with a signed Passport that binds the decision to the exact payload, so the system that executes the action can verify it was authorized and was not changed on the way.
- Deterministic: the same request under the same policy always gets the same decision. No model sits in the decision path.
- Framework-agnostic: any agent, orchestrator, MCP client or backend calls one HTTP API, or embeds the engine in process.
- Verifiable: RS256 Passports with payload hashing, JWKS and single-use
jti; SDKs for Python and Node. - Auditable: hash-chained audit log and OpenTelemetry traces for every decision.
Contents
- How it works
- Quickstart
- Integrations
- Decisions
- Security
- Documentation
- Status and roadmap
- Contributing
How it works
flowchart LR
P["Agent, orchestrator or tool<br/>(any framework, any model)"] -->|DecisionRequest| AXG{{AXG}}
AXG -->|ALLOW + Passport| X["Executor verifies the Passport,<br/>then acts"]
AXG -->|SUGGEST / CONFIRM| H[Human in the loop]
AXG -->|BLOCK| D[Denied]
AXG -.->|spans + metrics| O[(OpenTelemetry)]
AXG -.->|hash-chained records| A[(Audit log)]
- The caller authenticates with an API key and sends a
DecisionRequest: who acts (agent and permissions), what it wants to do (action_type,payload) and how sure the proposer is (llm.confidence). - AXG loads the policy plugin, evaluates its rules, enforces agent permissions and computes risk, confidence and uncertainty scores. The strictest outcome wins.
ALLOWresponses carry a Passport. The executor verifies it with an SDK before acting. Everything else carries a human-readable reason and machine-readable audit flags.
AXG never calls a model and never executes the action itself. It is not an LLM wrapper, a prompt framework or an agent framework.
Quickstart
Run the server with an API key for your app:
export AXG_KEY=$(openssl rand -hex 32)
export AXG_CLIENTS="[{\"client_id\":\"quickstart\",\"key_sha256\":\"$(python3 -c "import hashlib,os;print(hashlib.sha256(os.environ['AXG_KEY'].encode()).hexdigest())")\",\"app_ids\":[\"*\"],\"permissions\":[\"*\"]}]"
docker run --rm -p 8090:8090 -e AXG_CLIENTS="$AXG_CLIENTS" ghcr.io/pinheirodps/axg:latest
Ask for decisions (from a clone of this repository, which provides the example requests):
# A coding agent wants to read a file: ALLOW, with a Passport
curl -s localhost:8090/v1/decisions -H "Authorization: Bearer $AXG_KEY" \
-H "Content-Type: application/json" -d @examples/allow.json
# The same agent wants to run `rm -rf /`: BLOCK
curl -s localhost:8090/v1/decisions -H "Authorization: Bearer $AXG_KEY" \
-H "Content-Type: application/json" -d @examples/block.json
{
"decision": "BLOCK",
"plugin_version": "claude-code@0.1.0",
"reason": "This command can irreversibly destroy files or devices.",
"rules_triggered": [{"id": "destructive_shell_command", "decision": "BLOCK", "reason": "..."}],
"scores": {"risk_score": 1.0, "risk_level": "high", "final_confidence": 0.49},
"passport": null
}
Or install from PyPI and embed the engine in a Python process (or run the CLI directly):
pip install axg # core engine, HTTP API and CLI (use "axg[otel]" for OpenTelemetry export)
pip install axg-python-sdk # verify Passports and exchange approval tickets in Python
npm install axg-node-sdk # verify Passports and exchange approval tickets in Node.js / TypeScript
import asyncio
from pathlib import Path
from axg import DecisionEngine, DecisionRequest
from axg.plugin_loader import PluginLoader
engine = DecisionEngine(loader=PluginLoader(Path("plugins")))
async def main():
decision = await engine.decide(DecisionRequest(
execution_id="exec-1", tenant_id="acme", app_id="claude-code", plugin_id="claude-code",
source="coding_agent", action_type="Bash", payload={"command": "git push --force origin main"},
llm={"confidence": 0.92},
))
print(decision.decision.value, "-", decision.reason)
# CONFIRM - This Git operation can discard work or rewrite shared history.
asyncio.run(main())
Integrations
| Where your agents run | Integration |
|---|---|
| Any language or framework | HTTP API, plus the Python and Node SDKs to verify Passports |
| MCP servers and tools | verify_mcp_tool_call / verifyMcpToolCall: a tool checks that AXG authorized exactly the call it received |
| Any MCP server (Streamable HTTP) | MCP gateway: a proxy that decides every tools/call, including human approvals |
| AWS Bedrock AgentCore Gateway | REQUEST interceptor (Lambda) that decides before Cedar |
| Microsoft Agent Governance Toolkit | IExternalPolicyBackend for .NET |
| Claude Code | PreToolUse hook with a policy for shell and file tools |
| ticket2pr (Jira ticket → pull requests) | Guide and a least-privilege policy for its headless Claude Code agent |
| Observability | OpenTelemetry traces and metrics over OTLP |
Example policies live in plugins/: budget_guard (AI spend), claude-code (coding agents), ticket2pr (a headless coding agent driven from Jira tickets), finnorte (personal finance writes) and pocket_lawyer (legal assistant). Write your own with the policy guide.
Decisions
| Decision | Meaning | Passport |
|---|---|---|
ALLOW |
Safe to execute automatically | Yes, for authenticated callers outside shadow mode |
SUGGEST |
Show as a recommendation; do not execute silently | After human approval |
CONFIRM |
A human must confirm before execution | After human approval |
BLOCK |
Denied by policy or missing permission | No |
Precedence is BLOCK > CONFIRM > SUGGEST > ALLOW: the strictest applicable outcome wins. CONFIRM and SUGGEST carry a signed approval ticket: the right person approves, and AXG exchanges the ticket for a single-use Passport, with no state kept in AXG (human approvals). Errors never fail open: a policy that cannot be loaded, or a Passport that cannot be signed, results in CONFIRM. See how AXG decides.
Security
- Authenticated callers. API keys, stored as SHA-256, bind each caller to the apps it may request decisions for and cap the permissions it may grant its agents. Anonymous callers are rejected (
401) or, in migration mode, can never receiveALLOW. - Passport v2. A short-lived RS256 JWT with
jti,nbf, tenant, caller (azp), policy version and a canonical hash of the whole actionable payload. Keys are published as JWKS, with rotation. - Hardening. Request size limits, per-caller rate limits, no dynamic code in policies, allow-listed remote policies, a hash-chained audit log, pinned dependencies and actions, SBOM and provenance on images.
Read the security model before exposing AXG outside a private network. Report vulnerabilities privately as described in SECURITY.md.
Documentation
| Topic | |
|---|---|
| Concepts | Decision flow, scores, uncertainty gate, fail-safe principles |
| Writing policies | Plugin format, rules and operators, permissions, validation |
| Human approvals | Approval tickets, who approves, exchanging a ticket for a Passport |
| Signed context | Facts vouched for by trusted services, so rules do not depend on the caller's word |
| Passport | Claims, verification in Python and Node, replay protection, key rotation, MCP |
| API and contracts | Endpoints, request and response fields, errors, JSON Schemas |
| Configuration and deployment | Environment variables, Docker, production checklist |
| Security model | Trust boundaries and threat model |
| Observability | OpenTelemetry spans, events and metrics |
| Changelog | Release notes |
Status and roadmap
AXG is beta (v0.4.1) and runs in production. Packages are published on PyPI (axg, axg-python-sdk) and npm (axg-node-sdk) with provenance attestations, and multi-arch container images ship at ghcr.io/pinheirodps/axg. The API may change before 1.0; breaking changes are versioned in the contracts and listed in the changelog.
Contributing
Contributions are welcome. Start with CONTRIBUTING.md and the code of conduct. CI requires at least 98% test coverage of the core and integrations.
pip install -e ".[otel,test]"
python -m pytest --cov=axg --cov=integrations --cov-fail-under=98
python -m uvicorn axg.api:app --reload --port 8090
License
AXG MCP questions
Does AXG use an LLM to make decisions?
No, AXG is a deterministic engine where the same request under the same policy always gets the same decision without a model in the decision path.
How can I verify that an action was authorized by AXG?
AXG issues signed RS256 Passports that bind the decision to the exact payload, which can be verified using the provided Python or Node.js SDKs.
What are the possible decision outcomes?
AXG returns one of four outcomes: ALLOW (safe to execute), SUGGEST (recommendation), CONFIRM (requires human intervention), or BLOCK (denied).