@agentvalet/mcp-server 1.3.0 → 1.6.0

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/gate-client.js

@@ -0,0 +1,159 @@
+// apps/mcp-server/src/gate-client.ts
+//
+// A thin, dependency-free client over AgentValet's public governance contract.
+// It does NOT implement policy, brokering, or audit. Those live in the proxy.
+// It only does two things:
+//
+//   1. Send a request to the public gate (POST /v1/actions) or the Observe
+//      relay (POST /v1/observe/actions).
+//   2. Map the wire response to exactly one of the six documented decisions, so
+//      a connector switches on a single discriminated union instead of
+//      re-deriving status-code semantics in every integration.
+//
+// The full wire contract these mappings depend on is documented in
+// docs/contract/public-governance-gate.md. Keep this file and that doc in step.
+//
+// fetch is injectable (fetchImpl) so the mapping is testable without a network;
+// it defaults to the global fetch.
+/** Agent states that mean "the agent itself is halted", surfaced as a 403 by the
+ *  permission check. Distinct from a policy denial of an otherwise-healthy agent. */
+const SUSPENDED_REASONS = new Set(["agent_suspended", "circuit_breaker_open"]);
+function readField(body, key) {
+    if (body && typeof body === "object" && key in body) {
+        const v = body[key];
+        return typeof v === "string" ? v : undefined;
+    }
+    return undefined;
+}
+/**
+ * Pure mapper: a public-gate response (HTTP status + parsed body) to a decision.
+ * Exported so connectors and tests can classify a response they already hold.
+ *
+ * Mapping (POST /v1/actions):
+ *   2xx                                  -> allowed
+ *   202                                  -> pending_approval
+ *   403 reason in {agent_suspended,
+ *        circuit_breaker_open}           -> suspended
+ *   401 / 5xx                            -> error
+ *   other 4xx (402/403/412/429/...)      -> denied
+ */
+export function classifyGateResponse(status, body) {
+    if (status === 202) {
+        return {
+            decision: "pending_approval",
+            status,
+            approvalId: readField(body, "approval_id") ?? null,
+            message: readField(body, "message"),
+            raw: body,
+        };
+    }
+    if (status >= 200 && status < 300) {
+        return { decision: "allowed", status, data: body };
+    }
+    if (status === 403) {
+        const reason = readField(body, "reason");
+        if (reason && SUSPENDED_REASONS.has(reason)) {
+            return { decision: "suspended", status, reason, raw: body };
+        }
+    }
+    // Identity rejection and upstream/server failures are not policy decisions.
+    if (status === 401 || status >= 500) {
+        return {
+            decision: "error",
+            status,
+            code: readField(body, "code") ?? (status === 401 ? "unauthorized" : null),
+            correlationId: readField(body, "correlation_id"),
+            raw: body,
+        };
+    }
+    // Every other 4xx (402 billing, 403 policy, 412 not-connected, 429 rate) is a
+    // governance refusal of an otherwise-healthy agent.
+    return {
+        decision: "denied",
+        status,
+        reason: readField(body, "reason") ?? readField(body, "error") ?? null,
+        correlationId: readField(body, "correlation_id"),
+        raw: body,
+    };
+}
+async function parseBody(res) {
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Call the public governance gate (POST /v1/actions) and return a classified
+ * outcome. Never throws for a gate response or a transport failure: a transport
+ * failure resolves to a GateError with code "network_error" so callers handle
+ * every path through the same switch.
+ */
+export async function callGate(client, req) {
+    const doFetch = client.fetchImpl ?? fetch;
+    const requestBody = {
+        platform: req.platform,
+        endpoint: req.endpoint,
+        method: req.method,
+        scope: req.scope,
+        ...(req.data !== undefined ? { data: req.data } : {}),
+        ...(req.connection_id ? { connection_id: req.connection_id } : {}),
+    };
+    let res;
+    try {
+        res = await doFetch(`${client.proxyUrl}/v1/actions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${client.token}`, "Content-Type": "application/json" },
+            body: JSON.stringify(requestBody),
+        });
+    }
+    catch (err) {
+        return {
+            decision: "error",
+            status: 0,
+            code: "network_error",
+            raw: { error: err instanceof Error ? err.message : String(err) },
+        };
+    }
+    return classifyGateResponse(res.status, await parseBody(res));
+}
+/**
+ * Call the Observe relay (POST /v1/observe/actions). The relay is audit-only and
+ * passes the upstream status through, so a completed relay always resolves to
+ * GateObserved regardless of the upstream status. The BYO credential rides as a
+ * header and never enters the request body. A transport failure resolves to a
+ * GateError with code "network_error".
+ */
+export async function observe(client, req) {
+    const doFetch = client.fetchImpl ?? fetch;
+    const relayBody = {
+        platform: req.platform,
+        endpoint: req.endpoint,
+        method: req.method,
+        ...(req.action !== undefined ? { action: req.action } : {}),
+        ...(req.body !== undefined ? { body: req.body } : {}),
+    };
+    let res;
+    try {
+        res = await doFetch(`${client.proxyUrl}/v1/observe/actions`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${client.token}`,
+                "Content-Type": "application/json",
+                "X-AV-Observe-Credential": req.credential,
+            },
+            body: JSON.stringify(relayBody),
+        });
+    }
+    catch (err) {
+        return {
+            decision: "error",
+            status: 0,
+            code: "network_error",
+            raw: { error: err instanceof Error ? err.message : String(err) },
+        };
+    }
+    return { decision: "observed", status: res.status, data: await parseBody(res) };
+}

package/dist/index.js

@@ -22,8 +22,9 @@ import { validateConfig } from "./config.js";
 import { renderInstructions } from "./instructions.js";
 import { signJWT } from "./auth.js";
 import { ALLOWED_METHODS, ALL_TOOLS } from "./tools/schemas.js";
-import { handleListPlatforms, handleUsePlatform, handleAgentRegister, handleAgentStatus, handleAuthzenEvaluate, handleListMyPendingActions, handleReportSelfDiagnostic, } from "./tools/handlers.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") {
@@ -143,6 +173,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         return await handleReportSelfDiagnostic(ctx, args);
     }
+    if (name === "request_platform_access") {
+        if (!args || typeof args.platform !== "string") {
+            return errorContent("Invalid or missing argument: platform is required");
+        }
+        return await handleRequestPlatformAccess(ctx, args);
+    }
     return {
         content: [{ type: "text", text: `Unknown tool: ${name}` }],
         isError: true,
@@ -160,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 {
@@ -114,8 +121,15 @@ export async function handleUsePlatform(ctx, params, progressToken) {
             return await waitForApproval(ctx, approvalId, params, progressToken);
         }
     }
-    if (!response.ok)
-        return errorContent(`Proxy error ${response.status}: ${body}`);
+    if (!response.ok) {
+        // 403 is the access-denied / scope-not-granted code returned by the
+        // proxy's authorize pipeline (see apps/proxy/src/pipeline/authorize.ts).
+        // Point the agent at request_platform_access instead of dead-ending it.
+        const hint = response.status === 403
+            ? "  You can call request_platform_access({ platform, scope, reason }) to ask an org admin to grant this."
+            : "";
+        return errorContent(`Proxy error ${response.status}: ${body}${hint}`);
+    }
     return jsonContent(body);
 }
 async function waitForApproval(ctx, approvalId, originalCall, progressToken) {
@@ -280,6 +294,59 @@ export async function handleListMyPendingActions(ctx) {
         return errorContent(`Proxy error ${response.status}: ${text}`);
     return jsonContent(text);
 }
+export async function handleRequestPlatformAccess(ctx, args) {
+    const gate = await requireCredentials(ctx);
+    if (gate)
+        return gate;
+    const platform = typeof args.platform === "string" ? args.platform : "";
+    if (!platform)
+        return errorContent("platform is required");
+    const scope = typeof args.scope === "string" ? args.scope : undefined;
+    const reason = typeof args.reason === "string" ? args.reason : undefined;
+    let submit;
+    try {
+        submit = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/access-request`, {
+            method: "POST",
+            body: JSON.stringify({ platform, scope, reason }),
+        });
+    }
+    catch (err) {
+        return errorContent(diagnoseNetworkError(err, ctx.PROXY_URL));
+    }
+    if (!submit.ok && submit.status !== 202 && submit.status !== 200) {
+        const t = await submit.text();
+        return errorContent(`Access request failed (${submit.status}): ${t}`);
+    }
+    const submitted = (await submit.json());
+    const token = submitted.request_token;
+    if (!token)
+        return errorContent("Access request did not return a token.");
+    // Poll the request status for ~50s (2s interval), matching use_platform UX.
+    const deadline = Date.now() + 50_000;
+    while (Date.now() < deadline) {
+        await sleep(2000);
+        let statusRes;
+        try {
+            statusRes = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/access-request/status/${encodeURIComponent(token)}`, { method: "GET" });
+        }
+        catch {
+            continue;
+        }
+        if (!statusRes.ok)
+            continue;
+        const s = (await statusRes.json());
+        if (s.status === "approved") {
+            return jsonContent(JSON.stringify({ status: "approved", message: "Access granted — retry your original use_platform call." }));
+        }
+        if (s.status === "denied") {
+            return jsonContent(JSON.stringify({ status: "denied", message: "An admin denied this access request." }));
+        }
+    }
+    return jsonContent(JSON.stringify({
+        status: "pending",
+        message: "Request submitted and awaiting admin approval. Retry your call later.",
+    }));
+}
 export async function handleReportSelfDiagnostic(ctx, args) {
     const gate = await requireCredentials(ctx);
     if (gate)

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"],
     },
@@ -261,6 +265,27 @@ export const LIST_MY_PENDING_ACTIONS_TOOL = {
         required: ["pending", "recently_completed"],
     },
 };
+export const REQUEST_PLATFORM_ACCESS_TOOL = {
+    name: "request_platform_access",
+    description: "request_platform_access: Ask an org admin to grant this agent access to a platform it is currently blocked from. Call this when use_platform returns an access-denied error. Input: platform (string, required), scope (string, optional — the specific scope you need), reason (string, optional — why you need it). The call waits up to ~50s for an admin decision. Returns: { status: \"approved\"|\"pending\"|\"denied\", message }. On \"approved\", retry your original use_platform call. On \"pending\", the request is queued; retry later. Auth: Bearer agent JWT (sent automatically).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            platform: { type: "string", description: "Platform ID (e.g. github, slack)" },
+            scope: { type: "string", description: "Optional specific scope needed (e.g. repo:read)" },
+            reason: { type: "string", description: "Optional short reason for the request" },
+        },
+        required: ["platform"],
+    },
+    outputSchema: {
+        type: "object",
+        properties: {
+            status: { type: "string", enum: ["approved", "pending", "denied"] },
+            message: { type: "string" },
+        },
+        required: ["status"],
+    },
+};
 export const ALL_TOOLS = [
     LIST_PLATFORMS_TOOL,
     USE_PLATFORM_TOOL,
@@ -269,4 +294,5 @@ export const ALL_TOOLS = [
     AUTHZEN_EVALUATE_TOOL,
     REPORT_SELF_DIAGNOSTIC_TOOL,
     LIST_MY_PENDING_ACTIONS_TOOL,
+    REQUEST_PLATFORM_ACCESS_TOOL,
 ];

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "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"
@@ -35,7 +28,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/MCSEdwin/agentvalet.git",
-    "directory": "apps/mcp-server"
+    "directory": "packages/mcp-server"
   },
   "keywords": [
     "ai",
@@ -43,5 +36,12 @@
     "mcp",
     "agentvalet"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}