@ackuity/inline-proxy 0.7.1 → 0.7.4

package/README.md

@@ -213,6 +213,56 @@ Then run:
 docker compose up
 ```
 
+## Using Server Mode with OAuth / Authenticated MCP Servers
+
+If your MCP server requires authentication (e.g. OAuth, API keys, or session tokens), **server mode** is the recommended approach. The proxy runs as a standalone HTTP service, so authentication is handled entirely between your agent and the MCP server — the proxy transparently forwards headers and credentials while still intercepting tool calls for evaluation.
+
+### Why server mode for authenticated setups
+
+In stdio mode, the proxy spawns the MCP server as a child process, which makes it difficult to pass authentication context. In server mode, the proxy sits between your agent and an already-authenticated MCP server over HTTP, so:
+
+- Your agent authenticates with the MCP server as usual (OAuth flows, bearer tokens, etc.)
+- The proxy intercepts only `tools/call` requests for security evaluation
+- All other traffic (including auth handshakes) passes through unchanged
+
+### Example: OAuth-protected MCP server
+
+```bash
+# 1. Start your MCP server (handles its own OAuth)
+your-mcp-server --port 5000
+
+# 2. Start the Ackuity proxy in front of it
+npx @ackuity/inline-proxy --mode server --target http://localhost:5000/mcp --port 7500
+
+# 3. Point your agent to the proxy instead of the MCP server
+# Agent connects to http://localhost:7500/mcp
+```
+
+Your agent's existing authentication flow (OAuth redirects, token refresh, etc.) works as before — just change the MCP endpoint URL to point to the proxy.
+
+### Token expiry
+
+If the MCP server returns a `401 Unauthorized` or `403 Forbidden`, the token has expired. Your agent is responsible for refreshing the token with the OAuth provider and retrying the request — the proxy passes these status codes through unchanged.
+
+### Example: Agent passing a bearer token
+
+```typescript
+// Your agent sends requests to the proxy, which forwards to the MCP server
+const response = await fetch("http://localhost:7500/mcp", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "Authorization": "Bearer <your-oauth-token>",  // Passed through to MCP server
+  },
+  body: JSON.stringify({
+    jsonrpc: "2.0",
+    method: "tools/call",
+    params: { name: "delete_record", arguments: { id: 123 } },
+  }),
+});
+// The proxy evaluates the tool call with Ackuity before forwarding
+```
+
 ## Fail-Closed Behavior
 
 If the Inline Decision Engine is unreachable or returns an error (e.g. invalid token), the proxy **blocks the tool call** rather than forwarding it. This prevents destructive operations from slipping through during outages.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ackuity/inline-proxy",
-  "version": "0.7.1",
+  "version": "0.7.4",
   "license": "MIT",
   "type": "module",
   "main": "dist/main.js",
   "bin": {
-    "ackuity-mcp-proxy": "dist/main.js"
+    "inline-proxy": "dist/main.js"
   },
   "scripts": {
     "build": "tsc && npx biome check src/",