@agentvalet/mcp-server 1.4.0 → 1.6.1

package/README.md

@@ -1,67 +1,70 @@
-# @agentvalet/mcp-server
-
-MCP server that lets AI agents (Claude Code, Cursor, Codex CLI, etc.) call approved external platforms through the AgentValet proxy.
-
-## Quick start
-
-```bash
-npx @agentvalet/register   # registers this machine as an agent, writes config
-```
-
-The CLI writes env vars and optionally updates `.mcp.json` or `.cursor/mcp.json` automatically.
-
-## Manual configuration
-
-Add to your `.mcp.json` or equivalent:
-
-```json
-{
-  "mcpServers": {
-    "agentvalet": {
-      "command": "npx",
-      "args": ["-y", "@agentvalet/mcp-server"],
-      "env": {
-        "AGENT_ID": "agt_...",
-        "OWNER_ID": "...",
-        "PROXY_URL": "https://api.agentvalet.ai",
-        "AGENT_PRIVATE_KEY_PATH": "/path/to/agent.key"
-      }
-    }
-  }
-}
-```
-
-## Environment variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `AGENT_ID` | Yes | Agent ID from registration |
-| `OWNER_ID` | Yes | Owner ID from registration |
-| `PROXY_URL` | Yes | AgentValet proxy URL |
-| `AGENT_PRIVATE_KEY_PATH` | One of three | Path to PEM private key file |
-| `AGENT_PRIVATE_KEY` | One of three | Raw PEM or `\n`-escaped single-line PEM |
-| `AGENT_PRIVATE_KEY_B64` | One of three | Base64-encoded PEM |
-| `MCP_TRANSPORT` | No | Set to `http` to use HTTP transport instead of STDIO |
-| `MCP_PORT` | No | Port for HTTP transport (default: `3100`) |
-
-## Tools
-
-| Tool | Auth | Description |
-|------|------|-------------|
-| `list_platforms` | JWT | List platforms and scopes this agent has access to |
-| `use_platform` | JWT | Call an external platform API through the proxy |
-| `agent_register` | None | Self-register a new agent with an owner |
-| `agent_status` | None | Poll registration approval status |
-| `authzen_evaluate` | None | Check if this agent has access to a platform scope |
-
-## Transports
-
-**STDIO (default)** — compatible with all MCP hosts (Claude Code, Cursor, Codex CLI).
-
-**HTTP** — set `MCP_TRANSPORT=http` and optionally `MCP_PORT=3100`. Uses `StreamableHTTPServerTransport`.
-
-## Architecture
-
-Each tool call signs a short-lived RS256 JWT (`exp: 60s`) using the agent's private key. The JWT is verified by the AgentValet proxy, which checks permissions and forwards the request to the target platform using stored credentials.
-
-The agent never sees platform credentials. The proxy decrypts them in-memory at call time and discards them after the upstream request completes.
+# @agentvalet/mcp-server
+
+MCP server that lets AI agents (Claude Code, Cursor, Codex CLI, etc.) call approved external platforms through the AgentValet proxy.
+
+## Quick start
+
+```bash
+npx @agentvalet/register   # registers this machine as an agent, writes config
+```
+
+The CLI writes env vars and optionally updates `.mcp.json` or `.cursor/mcp.json` automatically.
+
+## Manual configuration
+
+Add to your `.mcp.json` or equivalent:
+
+```json
+{
+  "mcpServers": {
+    "agentvalet": {
+      "command": "npx",
+      "args": ["-y", "@agentvalet/mcp-server"],
+      "env": {
+        "AGENT_ID": "agt_...",
+        "OWNER_ID": "...",
+        "PROXY_URL": "https://api.agentvalet.ai",
+        "AGENT_PRIVATE_KEY_PATH": "/path/to/agent.key"
+      }
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AGENT_ID` | Yes | Agent ID from registration |
+| `OWNER_ID` | Yes | Owner ID from registration |
+| `PROXY_URL` | Yes | AgentValet proxy URL |
+| `AGENT_PRIVATE_KEY_PATH` | One of three | Path to PEM private key file |
+| `AGENT_PRIVATE_KEY` | One of three | Raw PEM or `\n`-escaped single-line PEM |
+| `AGENT_PRIVATE_KEY_B64` | One of three | Base64-encoded PEM |
+| `MCP_TRANSPORT` | No | Set to `http` to use HTTP transport instead of STDIO |
+| `MCP_PORT` | No | Port for HTTP transport (default: `3100`) |
+
+## Tools
+
+| Tool | Auth | Description |
+|------|------|-------------|
+| `list_platforms` | JWT | List platforms and scopes this agent has access to |
+| `use_platform` | JWT | Call an external platform API through the proxy (blocks for owner approval when required) |
+| `authzen_evaluate` | JWT | Pre-check whether this agent has access to a platform scope, without making the call |
+| `list_my_pending_actions` | JWT | List this agent's pending approvals and actions completed in the last 24h |
+| `request_platform_access` | JWT | Ask an org admin to grant access to a platform the agent is blocked from |
+| `report_self_diagnostic` | JWT | Lodge a self-report (error/warning/info) with the owner |
+| `agent_register` | None | Self-register a new agent with an owner |
+| `agent_status` | None | Poll registration approval status |
+
+## Transports
+
+**STDIO (default)** — compatible with all MCP hosts (Claude Code, Cursor, Codex CLI).
+
+**HTTP** — set `MCP_TRANSPORT=http` and optionally `MCP_PORT=3100`. Uses `StreamableHTTPServerTransport`.
+
+## Architecture
+
+Each tool call signs a short-lived RS256 JWT (`exp: 60s`) using the agent's private key. The JWT is verified by the AgentValet proxy, which checks permissions and forwards the request to the target platform using stored credentials.
+
+The agent never sees platform credentials. The proxy decrypts them in-memory at call time and discards them after the upstream request completes.

package/dist/index.js

@@ -24,6 +24,7 @@ import { signJWT } from "./auth.js";
 import { ALLOWED_METHODS, ALL_TOOLS } from "./tools/schemas.js";
 import { handleListPlatforms, handleUsePlatform, handleAgentRegister, handleAgentStatus, handleAuthzenEvaluate, handleListMyPendingActions, handleReportSelfDiagnostic, handleRequestPlatformAccess, } from "./tools/handlers.js";
 import { errorContent } from "./net.js";
+import { getPermissionsVersion, recordPermissionsVersion, startPermissionsWatcher, } from "./permissions-watcher.js";
 // ---------------------------------------------------------------------------
 // Startup env validation
 // ---------------------------------------------------------------------------
@@ -40,7 +41,12 @@ process.stderr.write(`[mcp-server] config ok | agent=${AGENT_ID} | owner=${OWNER
 // ---------------------------------------------------------------------------
 // MCP server setup
 // ---------------------------------------------------------------------------
-const server = new Server({ name: "agentvalet", version: "1.0.0" }, { capabilities: { tools: {} }, instructions: renderInstructions(undefined) });
+const server = new Server({ name: "agentvalet", version: "1.0.0" }, 
+// listChanged: the permissions watcher pushes notifications/tools/list_changed
+// when the agent's effective platform spec moves under it (see
+// permissions-watcher.ts). Declaring the capability is what makes the SDK
+// allow that notification.
+{ capabilities: { tools: { listChanged: true } }, instructions: renderInstructions(undefined) });
 // The config + server bundle threaded into auth + handlers (see context.ts) —
 // keeps those modules free of globals.
 const ctx = {
@@ -65,19 +71,42 @@ void (async () => {
         const token = await signJWT(ctx);
         const ac = new AbortController();
         const timer = setTimeout(() => ac.abort(), 4_000);
-        await fetch(`${PROXY_URL}/v1/agent/permissions`, {
+        const res = await fetch(`${PROXY_URL}/v1/agent/permissions`, {
             method: "GET",
             headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
             signal: ac.signal,
         }).finally(() => clearTimeout(timer));
+        // Seed the watcher's baseline so the first poll compares against the spec
+        // as it was at boot, not against "unknown".
+        if (res.ok) {
+            const parsed = (await res.json());
+            recordPermissionsVersion(parsed?.data?.version ?? parsed?.version);
+        }
     }
     catch {
         // best-effort warmup only
     }
 })().catch(() => { });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: ALL_TOOLS,
-}));
+// Stamp list_platforms with the current permissions version. This is the half
+// of the staleness fix that actually reaches the model: after a
+// tools/list_changed push the host re-reads tools/list, and a description that
+// genuinely differs from the one already in context is what tells the model its
+// cached platform spec is no longer the live one.
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const version = getPermissionsVersion();
+    if (!version)
+        return { tools: ALL_TOOLS };
+    return {
+        tools: ALL_TOOLS.map((tool) => tool.name === "list_platforms"
+            ? {
+                ...tool,
+                description: `${tool.description}\nCurrent permissions version: ${version}. If you are holding a ` +
+                    `list_platforms result from a different version, it is STALE — call list_platforms ` +
+                    `again before relying on its scopes or requireApproval flags.`,
+            }
+            : tool),
+    };
+});
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     if (name === "list_platforms") {
@@ -114,6 +143,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             scope: args.scope,
             data: bodyArg,
             ...(typeof args.connection_id === "string" ? { connection_id: args.connection_id } : {}),
+            ...(typeof args.reason === "string" ? { reason: args.reason } : {}),
         }, progressToken);
     }
     if (name === "agent_register") {
@@ -166,3 +196,6 @@ else {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+// Started only after the transport is connected — notifications have nowhere to
+// go before that. No-op without credentials or when AV_PERMISSIONS_POLL_MS=0.
+startPermissionsWatcher(ctx);

package/dist/instructions.js

@@ -12,7 +12,7 @@ When the user says "use AV", "ask Valet", "via agentvalet", or names this broker
 If \`list_platforms\` does NOT return the requested platform, tell the user "AgentValet doesn't cover <platform> yet — want me to use a different MCP, or request the integration via your AgentValet owner?" Do not silently fall back to another MCP server or to direct API calls.
 
 Tool selection:
-1. Call \`list_platforms\` first to discover approved platforms and scopes for this agent. Cache the result for the session — re-call only if the user mentions a new connection or after a \`use_platform\` failure.
+1. Call \`list_platforms\` first to discover approved platforms and scopes for this agent. You may reuse the result within a turn, but do NOT treat it as good for the whole session — an owner can change a grant (scopes, or whether an action needs their approval) at any moment, and the tool description carries a \`Current permissions version\` that tells you when yours is stale. Re-call \`list_platforms\` if that version changes, if the user mentions a connection or permission change, or after any \`use_platform\` failure. Revalidation is cheap.
 2. Call \`authzen_evaluate\` before destructive scopes (\`*.delete\`, \`stripe:charge\`, \`mail:send\`) — these always require human approval. Tell the user approval may be required before invoking them.
 3. Call \`use_platform\` with the exact platform, endpoint, method, and scope returned by \`list_platforms\`.
 

package/dist/permissions-watcher.js

@@ -0,0 +1,132 @@
+// apps/mcp-server/src/permissions-watcher.ts
+//
+// Keeps the host's view of the agent's platform spec from going stale.
+//
+// The problem this exists for: an owner flips a grant in the dashboard (say,
+// require_approval on Slack) mid-session. The agent had already called
+// list_platforms and cached the answer in its context, so it kept reasoning
+// from the pre-change spec — the proxy enforced the new rule at call time, but
+// nothing ever told the agent the spec had moved.
+//
+// GET /v1/agent/permissions returns a deterministic `version` hash over the
+// effective spec (scopes + requireApproval + connections). We poll it with
+// If-None-Match, so an unchanged spec costs a 304 with no body. When the hash
+// does move we emit notifications/tools/list_changed; the host re-reads
+// tools/list, and because the list_platforms description is stamped with the
+// current version (see index.ts), the description the model sees actually
+// differs — which is what gets the stale cache invalidated in practice. A bare
+// list_changed on an otherwise-identical tool list would be a no-op.
+//
+// Note this only works on a long-lived transport. The in-proxy MCP endpoint
+// (apps/proxy/src/routes/mcp.ts) is deliberately stateless — a fresh Server per
+// request — so it has no server→client channel and cannot push at all; there,
+// cheap revalidation via the 304 path is the whole story.
+import { signJWT } from "./auth.js";
+import { fetchWithTimeout } from "./net.js";
+const DEFAULT_POLL_MS = 60_000;
+// Floor so a typo in the env var can't turn an agent into a polling hammer
+// against the proxy.
+const MIN_POLL_MS = 10_000;
+let currentVersion = null;
+let timer = null;
+export function getPermissionsVersion() {
+    return currentVersion;
+}
+/**
+ * Record a version observed elsewhere (a normal list_platforms tool call).
+ * Returns true when this is a CHANGE from a previously-known version — the
+ * first observation only establishes the baseline and is not a change.
+ */
+export function recordPermissionsVersion(version) {
+    if (!version || typeof version !== "string")
+        return false;
+    const hadBaseline = currentVersion !== null;
+    const changed = hadBaseline && version !== currentVersion;
+    currentVersion = version;
+    return changed;
+}
+/** Test seam: forget everything the watcher has learned. */
+export function resetPermissionsVersion() {
+    currentVersion = null;
+}
+export function pollIntervalMs(raw = process.env.AV_PERMISSIONS_POLL_MS) {
+    if (raw === undefined || raw === "")
+        return DEFAULT_POLL_MS;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return 0; // 0 / invalid ⇒ disabled
+    return Math.max(parsed, MIN_POLL_MS);
+}
+/**
+ * One revalidation round-trip. Exported for tests. Returns true when the spec
+ * changed (and a notification was emitted).
+ */
+export async function checkPermissionsVersion(ctx) {
+    if (ctx.AGENT_PRIVATE_KEY_RAW === null)
+        return false;
+    let response;
+    try {
+        const token = await signJWT(ctx);
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+        };
+        if (currentVersion)
+            headers["If-None-Match"] = `"${currentVersion}"`;
+        response = await fetchWithTimeout(`${ctx.PROXY_URL}/v1/agent/permissions`, { method: "GET", headers }, 10_000);
+    }
+    catch {
+        return false; // transient — try again next tick
+    }
+    // Unchanged: the whole point of the conditional request.
+    if (response.status === 304)
+        return false;
+    if (!response.ok)
+        return false;
+    let version;
+    try {
+        const parsed = (await response.json());
+        const inner = (parsed && typeof parsed === "object" && "data" in parsed
+            ? parsed.data
+            : parsed);
+        if (inner && typeof inner.version === "string")
+            version = inner.version;
+    }
+    catch {
+        return false;
+    }
+    if (!recordPermissionsVersion(version))
+        return false;
+    try {
+        await ctx.server.notification({ method: "notifications/tools/list_changed" });
+    }
+    catch {
+        // Best-effort: a host that doesn't accept the notification still gets the
+        // corrected spec the next time it calls list_platforms.
+    }
+    return true;
+}
+/**
+ * Start background revalidation. No-op without credentials or when polling is
+ * disabled. The timer is unref'd so it can never hold the process open.
+ */
+export function startPermissionsWatcher(ctx) {
+    if (timer)
+        return;
+    if (ctx.AGENT_PRIVATE_KEY_RAW === null)
+        return;
+    const interval = pollIntervalMs();
+    if (interval === 0)
+        return;
+    timer = setInterval(() => {
+        void checkPermissionsVersion(ctx).catch(() => { });
+    }, interval);
+    // `unref` is absent in some non-Node runtimes; guard rather than assume.
+    timer.unref?.();
+}
+export function stopPermissionsWatcher() {
+    if (!timer)
+        return;
+    clearInterval(timer);
+    timer = null;
+}

package/dist/tools/handlers.js

@@ -6,6 +6,7 @@
 // module globals. Behavior is unchanged — pinned by test/introspection.test.ts.
 import { errorContent, jsonContent, tryParseJson, safeJsonParse, sleep, diagnoseNetworkError, fetchWithTimeout, } from "../net.js";
 import { requireCredentials, fetchWithAuth } from "../auth.js";
+import { recordPermissionsVersion } from "../permissions-watcher.js";
 export async function handleListPlatforms(ctx) {
     const gate = await requireCredentials(ctx);
     if (gate)
@@ -29,6 +30,9 @@ export async function handleListPlatforms(ctx) {
         ? parsed.data
         : parsed;
     if (inner && typeof inner === "object") {
+        // Keep the watcher's baseline in step with what the agent was just told, so
+        // a manual refresh doesn't trigger a spurious "changed" notification.
+        recordPermissionsVersion(inner.version);
         return {
             content: [{ type: "text", text: body }],
             structuredContent: inner,
@@ -91,6 +95,9 @@ export async function handleUsePlatform(ctx, params, progressToken) {
         scope: params.scope,
         ...(params.data !== undefined && { data: params.data }),
         ...(params.connection_id ? { connection_id: params.connection_id } : {}),
+        // Agent-supplied justification. Forwarded verbatim; the proxy normalizes
+        // and caps it before it reaches the approver's screen.
+        ...(params.reason ? { reason: params.reason } : {}),
     };
     let response;
     try {

package/dist/tools/schemas.js

@@ -7,7 +7,7 @@
 export const ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 export const LIST_PLATFORMS_TOOL = {
     name: "list_platforms",
-    description: "list_platforms: List the platforms and permission scopes this agent has access to.\nInput: None.\nReturns: { platforms: [{ platformId, platformName, scopes, requireApproval, connections? }], version: \"<hex>\" }. A platform includes `connections` only when it has 2+ usable accounts; pass the chosen connection_id to use_platform (omit for the default).\nVersion: a deterministic hash that only changes when the platform set or scopes change. Cache the value across calls in the same session — only refresh when you suspect platforms have changed (e.g. user mentions a new connection).\nAuth: Bearer JWT.",
+    description: "list_platforms: List the platforms and permission scopes this agent has access to.\nInput: None.\nReturns: { platforms: [{ platformId, platformName, scopes, requireApproval, connections? }], version: \"<hex>\" }. A platform includes `connections` only when it has 2+ usable accounts; pass the chosen connection_id to use_platform (omit for the default).\nVersion: a deterministic hash over the effective spec — it changes whenever the platform set, the scopes, or the requireApproval flags change. Compare it against the `Current permissions version` stamped on this description: if they differ, your cached result is stale and you must call list_platforms again before trusting it.\nAuth: Bearer JWT.",
     inputSchema: { type: "object", properties: {} },
     outputSchema: {
         type: "object",
@@ -46,7 +46,7 @@ export const LIST_PLATFORMS_TOOL = {
 };
 export const USE_PLATFORM_TOOL = {
     name: "use_platform",
-    description: "use_platform: Call an external platform API (Airtable, GitHub, Slack, Metabase, etc.) through the AgentValet proxy.\nInput: platform (string), endpoint (string), method (GET|POST|PUT|PATCH|DELETE), scope (string), body (object, optional — JSON request body for POST/PUT/PATCH/DELETE).\nReturns: upstream API response body. May take up to 50 seconds when the action requires owner approval — the call will block while we wait, then return the approved result transparently. If approval doesn't land in time, returns a `pending_approval` envelope and the action runs asynchronously; the user is notified when it completes.\nAuth: Bearer JWT.\nNote: legacy clients passing `data` instead of `body` are still accepted for backwards compatibility, but `body` is the canonical name.",
+    description: "use_platform: Call an external platform API (Airtable, GitHub, Slack, Metabase, etc.) through the AgentValet proxy.\nInput: platform (string), endpoint (string), method (GET|POST|PUT|PATCH|DELETE), scope (string), body (object, optional — JSON request body for POST/PUT/PATCH/DELETE), reason (string, optional — why you are making this call; shown to the human approver when the action is gated).\nReturns: upstream API response body. May take up to 50 seconds when the action requires owner approval — the call will block while we wait, then return the approved result transparently. If approval doesn't land in time, returns a `pending_approval` envelope and the action runs asynchronously; the user is notified when it completes.\nAuth: Bearer JWT.\nNote: legacy clients passing `data` instead of `body` are still accepted for backwards compatibility, but `body` is the canonical name.",
     inputSchema: {
         type: "object",
         properties: {
@@ -79,6 +79,10 @@ export const USE_PLATFORM_TOOL = {
                 type: "string",
                 description: "Optional. Target a specific connection when a platform has more than one connected (e.g. two GitHub orgs). Value is the connection id shown in the dashboard. Omit to use the default connection.",
             },
+            reason: {
+                type: "string",
+                description: "Optional but strongly encouraged. One sentence on WHY you are making this call. If the action requires owner approval, this is shown to the human who decides — without it their approval is a blind yes/no. Max 500 characters (longer is truncated). Plain text; markup is not rendered.",
+            },
         },
         required: ["platform", "endpoint", "method", "scope"],
     },

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "1.4.0",
+  "version": "1.6.1",
   "description": "AgentValet MCP server — lets AI agents call approved platforms via the AgentValet proxy",
+  "mcpName": "io.github.agentvalet/mcp-server",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -11,14 +12,6 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "jose": "^5.10.0"
@@ -34,8 +27,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/MCSEdwin/agentvalet.git",
-    "directory": "apps/mcp-server"
+    "url": "git+https://github.com/AgentValet/AgentValet.git",
+    "directory": "packages/mcp-server"
   },
   "keywords": [
     "ai",
@@ -43,5 +36,13 @@
     "mcp",
     "agentvalet"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "homepage": "https://github.com/AgentValet/AgentValet#readme",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}