Authorization and audit gateway for AI agent tool calls.
Nexus-MCP is a Python MCP server that authenticates every request, decides before execution whether an AI agent is allowed to run a tool, and records every attempt in an audit log.
Built for the Build, Ship, Shape: Amazon Developer Hackathon 2026 (Alexa+ track) as a self-hosted MCP server, and as a hands-on project to learn Python backend development, MCP and OAuth.
User
↓
Alexa+ (MCP client)
↓ MCP / Streamable HTTP + Bearer token
Nexus-MCP
↓
Authentication who is making the request? (invalid → 401)
↓
Authorization is this tool call allowed?
├── ALLOW → tool executes
└── DENY → tool is NOT executed
↓
Audit every attempt is recorded
↓
MCP response
AI agents can pick tools and act on behalf of users. MCP standardizes how an agent discovers and calls tools, but it does not decide whether the agent should. Not every action carries the same risk, so a system needs to:
- verify who is calling;
- apply a policy before a tool runs;
- allow or block individual tool calls;
- keep a structured, auditable record of every decision.
Nexus-MCP demonstrates this control flow at the MCP layer: an agent can request an action without automatically getting permission to execute it.
Three simulated tools demonstrate the different outcomes:
| Tool | Action | Risk | Decision |
|---|---|---|---|
get_customer |
READ | LOW | ✅ ALLOW |
create_order |
WRITE | MEDIUM | ✅ ALLOW |
cancel_order |
DESTRUCTIVE | HIGH | ❌ DENY |
A user asks Alexa+ to cancel order 1042. Alexa+ requests cancel_order(order_id=1042), Nexus validates the bearer token, the policy returns DENY, the tool is never invoked, an audit event is written with execution_status = NOT_EXECUTED, and the denial is returned to the client.
| Area | Choice |
|---|---|
| Language | Python |
| Protocol | MCP (minimum spec version 2025-11-25) |
| Transport | Streamable HTTP |
| MCP implementation | Official MCP Python SDK (2.x) |
| Authentication | OAuth 2.1 resource server: bearer JWTs validated locally against the provider's JWKS (PyJWT) |
| Authorization policy | Python mapping, deny by default |
| Audit | Append-only JSONL |
| Testing | pytest |
| Architecture | Modular monolith |
The reasoning behind each choice is recorded in docs/DECISIONS.md.
🟢 MVP complete. Hackathon build, Day 7.
Project definition ✅
Architecture ✅
MCP server ✅
Simulated tools ✅
Authorization engine ✅
Gateway + audit ✅
Authentication ✅ (service-level scopes supported)
Remote exposure ✅ (HTTPS tunnel for development)
Authenticated demo ✅ (MCP client over the tunnel)
Alexa+ add-on ⚪ (see "Alexa+ integration status")
The gateway is verified end to end with an authenticated MCP client over a public HTTPS tunnel. Connecting a deployed Alexa+ add-on requires the Alexa AI CLI, whose setup involves Node 24+, AWS profiles and a private package registry. See docs/RISKS-AND-FRICTION.md for what was attempted and learned.
1. Client → POST /mcp with Authorization: Bearer <token>
2. auth/ validates signature, issuer, expiry and scope → else 401
3. server.py thin MCP adapter: turns the call into gateway.call(...)
4. gateway.py the single path to any tool
5. authorization/ authorize(tool_name) → ALLOW | DENY (+ reason)
6. DENY → tool is not looked up and not called
ALLOW → tools/ executes the simulated tool
7. audit/ one JSONL event per attempt (arguments sanitized, no secrets)
8. server.py returns the MCP response (result or denial)
Authentication (auth/) never knows about the policy, and the policy (authorization/) never imports the tools. Architecture tests in tests/integration/ enforce these boundaries.
From the official Alexa+ MCP documentation:
- Two tiers. Tier 1 is a service-level token (
client_credentials, scopemcp:service). Tier 2 is a user-level token (authorization code + PKCE) used when account linking is enabled. - Unauthenticated requests must receive
401without aWWW-Authenticateheader. - The server publishes Protected Resource Metadata (RFC 9728). The authorization server publishes its metadata at
/.well-known/oauth-authorization-serverand supports PKCES256. - Alexa+ sends a
resourceparameter in its token requests. - Responses must complete in under 500 ms, and Alexa+ caches authentication metadata at deploy time.
Nexus supports both scope rules in its token validator: AUTH_REQUIRED_SCOPES (every scope must be present) and AUTH_ACCEPTED_SCOPES (at least one must be present, e.g. mcp:service mcp:tools).
Requires Python 3.10 or later.
git clone https://github.com/javtl/nexus-mcp.git
cd nexus-mcp
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env # fill in your values; never commit .env
pytest # unit and integration testsVariables are not loaded from .env automatically. Export them in your shell:
set -a; source .env; set +a| Variable | Purpose |
|---|---|
NEXUS_HOST / NEXUS_PORT (or PORT) |
Bind address and port |
NEXUS_PUBLIC_URL |
Public HTTPS URL of this server |
AUTH_ISSUER_URL |
OAuth authorization server (token issuer, compared literally, including a trailing slash if the provider uses one) |
AUTH_JWKS_URL |
JWKS endpoint used to verify token signatures |
AUTH_AUDIENCE |
Optional expected audience |
AUTH_REQUIRED_SCOPES |
Scopes a token must all carry |
AUTH_ACCEPTED_SCOPES |
Scopes of which a token must carry at least one |
AUDIT_FILE_PATH |
Audit log location (default data/audit.jsonl) |
The server refuses to start if authentication is not configured. There is intentionally no switch to disable it.
python -m nexus_mcp.serverEvery request to the MCP endpoint needs a valid bearer token from your authorization server. A request without one gets 401.
Remote clients cannot reach 127.0.0.1. For development, a Cloudflare quick tunnel works:
cloudflared tunnel --url http://localhost:8000Set NEXUS_PUBLIC_URL to the URL it prints and restart the server. A quick tunnel's URL changes every time cloudflared restarts, so it suits development and demos, not a stable production address.
scripts/mcp_smoke.py obtains a token through the OAuth client credentials flow, lists the tools and runs the three scenarios. It needs AUTH_TOKEN_URL, AUTH_CLIENT_ID, AUTH_CLIENT_SECRET and AUTH_SCOPE in your environment.
NEXUS_MCP_URL=https://<your-tunnel-host>/mcp python scripts/mcp_smoke.py
bash scripts/check_remote.sh https://<your-tunnel-host> # 401 without a token, metadata reachableExpected: get_customer and create_order succeed, cancel_order is denied, and the audit log gets one line per call.
cat data/audit.jsonlEach line records timestamp, request_id, tool_name, sanitized arguments, action_type, risk_level, decision, reason and execution_status (SUCCESS, FAILED or NOT_EXECUTED).
- The spy test. A fake tool counts its calls; a denied
cancel_ordergoes through the real policy and audit, and the test asserts the counter is0. - Audit failure. If the audit writer fails, a denied call is still never executed.
- Token validation. Expired, wrongly signed, wrong issuer, missing scope,
alg: noneand garbage tokens are all rejected, and error messages never contain the token. - Boundaries. Tests read the source and fail if
server.pyimports the tools, or ifauth/knows about authorization.
src/nexus_mcp/
├── server.py MCP entry point (HTTP/MCP boundary, thin adapters)
├── config.py settings from environment variables
├── gateway.py authorize → execute or block → audit
├── auth/ token validation (authentication)
├── authorization/ policy and ALLOW/DENY engine
├── tools/ simulated business tools
└── audit/ audit events, sanitizer, JSONL writer
tests/
├── unit/ per-module tests
└── integration/ end-to-end gateway flow and architecture boundaries
scripts/ demo client and remote checks
docs/ project documentation
| Document | Purpose |
|---|---|
docs/PROJECT.md |
What we are building and why |
docs/ARCHITECTURE.md |
How the system is structured |
docs/DECISIONS.md |
Technical decisions and their reasons |
docs/ROADMAP.md |
Build order and milestones |
docs/TICKETS.md |
Task-level work and Definition of Done |
docs/LEARNING_LOG.md |
What was learned along the way |
docs/RISKS-AND-FRICTION.md |
Risks and tooling friction |
AI_INSTRUCTIONS.md |
How AI assistants work on this project |
Lightweight GitFlow:
main stable milestones
↑
develop integration branch
↑
feature/<ticket-id>-<short-name>
Each feature gets its own branch, tests and review before merging into develop. Learning entries are tracked per feature as NX-xx.
- Secrets live in
.envor in the host's environment settings..envis git-ignored; only.env.exampleis committed. - Tokens, client secrets and private keys never appear in logs or audit records. Audit arguments are sanitized by key name as a safety net.
- Authentication answers who; authorization answers is it allowed. They are separate modules.
- Authorization denies by default: a tool missing from the policy is blocked, not allowed.
- Token validation pins the accepted algorithms and requires
issandexp. - A service-level token (
mcp:service) carries no user identity, so the policy decides per tool, not per person.
Tools are simulated and there is no database. The policy is a fixed table in code, with no roles or dynamic administration. The audit log is a local file. The development tunnel URL is temporary.
SaaS features, dashboards, frontends, complex RBAC, multi-tenancy, microservices, real commerce infrastructure, or AI-based authorization decisions.
To be decided.