@agentvalet/mcp-server 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,67 @@
+# @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.

package/dist/config.js

@@ -0,0 +1,34 @@
+import { readPrivateKeyFromEnv } from "./pem.js";
+import { importPKCS8 } from "jose";
+export async function validateConfig() {
+    const missing = [];
+    for (const key of ["AGENT_ID", "OWNER_ID", "PROXY_URL"]) {
+        if (!process.env[key])
+            missing.push(key);
+    }
+    if (missing.length > 0) {
+        process.stderr.write(`[mcp-server] Missing required environment variables: ${missing.join(", ")}\n`);
+        process.exit(1);
+    }
+    const agentId = process.env.AGENT_ID;
+    const ownerId = process.env.OWNER_ID;
+    const proxyUrl = process.env.PROXY_URL.replace(/\/$/, "");
+    let privateKeyPem = null;
+    let privateKey = null;
+    try {
+        privateKeyPem = readPrivateKeyFromEnv();
+    }
+    catch {
+        // No key provided — tools will return pending-activation response
+    }
+    if (privateKeyPem !== null) {
+        try {
+            privateKey = await importPKCS8(privateKeyPem, "RS256");
+        }
+        catch (err) {
+            process.stderr.write(`[mcp-server] Invalid private key: ${err instanceof Error ? err.message : err}\n`);
+            process.exit(1);
+        }
+    }
+    return { agentId, ownerId, proxyUrl, privateKeyPem, privateKey };
+}

package/dist/index.js

@@ -1,48 +1,12 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { SignJWT, importPKCS8 } from "jose";
-import { readFileSync } from "fs";
+import { SignJWT } from "jose";
+import { validateConfig } from "./config.js";
 // ---------------------------------------------------------------------------
 // Startup env validation
 // ---------------------------------------------------------------------------
-// Resolve AGENT_PRIVATE_KEY: accept raw key content or a path via AGENT_PRIVATE_KEY_PATH
-if (!process.env.AGENT_PRIVATE_KEY && process.env.AGENT_PRIVATE_KEY_PATH) {
-    try {
-        process.env.AGENT_PRIVATE_KEY = readFileSync(process.env.AGENT_PRIVATE_KEY_PATH, "utf-8").trim();
-    }
-    catch (err) {
-        process.stderr.write(`[mcp-server] Cannot read AGENT_PRIVATE_KEY_PATH: ${err instanceof Error ? err.message : err}\n`);
-        process.exit(1);
-    }
-}
-const REQUIRED_ENV = ["AGENT_PRIVATE_KEY", "AGENT_ID", "OWNER_ID", "PROXY_URL"];
-for (const key of REQUIRED_ENV) {
-    if (!process.env[key]) {
-        process.stderr.write(`[mcp-server] Missing required environment variable: ${key} (or AGENT_PRIVATE_KEY_PATH)\n`);
-        process.exit(1);
-    }
-}
-const AGENT_PRIVATE_KEY_RAW = process.env.AGENT_PRIVATE_KEY;
-const AGENT_ID = process.env.AGENT_ID;
-const OWNER_ID = process.env.OWNER_ID;
-const PROXY_URL = process.env.PROXY_URL.replace(/\/$/, "");
-// If the key is the sentinel value, defer key import — the guard in each tool
-// handler will return a user-friendly error before any signing attempt.
-let privateKey = null;
-if (AGENT_PRIVATE_KEY_RAW !== "PENDING_FIRST_CALL") {
-    const rawKey = AGENT_PRIVATE_KEY_RAW.trim();
-    const AGENT_PRIVATE_KEY = rawKey.startsWith("-----")
-        ? rawKey.replace(/\\n/g, "\n")
-        : `-----BEGIN PRIVATE KEY-----\n${rawKey}\n-----END PRIVATE KEY-----`;
-    try {
-        privateKey = await importPKCS8(AGENT_PRIVATE_KEY, "RS256");
-    }
-    catch (err) {
-        process.stderr.write(`[mcp-server] Invalid AGENT_PRIVATE_KEY: ${err instanceof Error ? err.message : err}\n`);
-        process.exit(1);
-    }
-}
+const { agentId: AGENT_ID, ownerId: OWNER_ID, proxyUrl: PROXY_URL, privateKeyPem: AGENT_PRIVATE_KEY_RAW, privateKey } = await validateConfig();
 // ---------------------------------------------------------------------------
 // JWT signing
 // ---------------------------------------------------------------------------
@@ -162,11 +126,6 @@ const AGENT_STATUS_TOOL = {
         required: ["token"],
     },
 };
-const AGENT_PERMISSIONS_TOOL = {
-    name: "agent_permissions",
-    description: "agent_permissions: List all platforms and permission scopes granted to this agent.\nInput: None.\nReturns: platforms array with platformId, platformName, scopes, requireApproval.\nAuth: Bearer JWT.",
-    inputSchema: { type: "object", properties: {} },
-};
 const AUTHZEN_EVALUATE_TOOL = {
     name: "authzen_evaluate",
     description: "authzen_evaluate: Evaluate whether this agent has access to a specific platform scope.\nInput: platform_id (string), scope (string).\nReturns: decision (boolean), reason (\"approved\"|\"denied\"|\"revoked\"|\"scope_not_granted\").\nAuth: None.",
@@ -185,24 +144,7 @@ const AUTHZEN_EVALUATE_TOOL = {
         required: ["platform_id", "scope"],
     },
 };
-const INTENT_RESOLVE_TOOL = {
-    name: "intent_resolve",
-    description: "intent_resolve: Resolve a natural-language intent to the exact AgentValet API action to call.\nInput: intent (string, required), context (object, optional).\nReturns: resolved (boolean), capability object with endpoint, auth_required, example_request, or suggestions array.\nAuth: None.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            intent: {
-                type: "string",
-                description: "Natural-language description of what the agent wants to do",
-            },
-            context: {
-                type: "object",
-                description: "Optional context object to aid resolution",
-            },
-        },
-        required: ["intent"],
-    },
-};
+// TODO: intent_resolve tool — planned for future release
 // ---------------------------------------------------------------------------
 // MCP server setup
 // ---------------------------------------------------------------------------
@@ -213,9 +155,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         USE_PLATFORM_TOOL,
         AGENT_REGISTER_TOOL,
         AGENT_STATUS_TOOL,
-        AGENT_PERMISSIONS_TOOL,
         AUTHZEN_EVALUATE_TOOL,
-        INTENT_RESOLVE_TOOL,
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -260,21 +200,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         return await handleAgentStatus(args.token);
     }
-    if (name === "agent_permissions") {
-        return await handleAgentPermissions();
-    }
     if (name === "authzen_evaluate") {
         if (!args || typeof args.platform_id !== "string" || typeof args.scope !== "string") {
             return errorContent("Invalid or missing arguments: platform_id and scope are required");
         }
         return await handleAuthzenEvaluate(args.platform_id, args.scope);
     }
-    if (name === "intent_resolve") {
-        if (!args || typeof args.intent !== "string") {
-            return errorContent("Invalid or missing argument: intent is required");
-        }
-        return await handleIntentResolve(args.intent, args.context);
-    }
     return {
         content: [{ type: "text", text: `Unknown tool: ${name}` }],
         isError: true,
@@ -288,12 +219,20 @@ function fetchWithTimeout(url, init, timeoutMs = 15_000) {
     const timer = setTimeout(() => ac.abort(), timeoutMs);
     return fetch(url, { ...init, signal: ac.signal }).finally(() => clearTimeout(timer));
 }
-async function bearerFetch(url, init) {
-    const token = await signJWT();
-    return fetchWithTimeout(url, {
-        ...init,
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init.headers },
-    });
+async function fetchWithAuth(url, init) {
+    const makeRequest = async () => {
+        const token = await signJWT();
+        return fetchWithTimeout(url, {
+            ...init,
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init.headers },
+        });
+    };
+    const response = await makeRequest();
+    // Retry once on 401 — the JWT may have been issued just before clock skew threshold
+    if (response.status === 401) {
+        return makeRequest();
+    }
+    return response;
 }
 function errorContent(message) {
     return { content: [{ type: "text", text: message }], isError: true };
@@ -302,13 +241,13 @@ function errorContent(message) {
 // Tool handlers
 // ---------------------------------------------------------------------------
 async function handleListPlatforms() {
-    if (AGENT_PRIVATE_KEY_RAW === "PENDING_FIRST_CALL") {
+    if (AGENT_PRIVATE_KEY_RAW === null) {
         await notifyBindSecret();
         return pendingFirstCallResponse();
     }
     let response;
     try {
-        response = await bearerFetch(`${PROXY_URL}/v1/agent/permissions`, { method: "GET", headers: {} });
+        response = await fetchWithAuth(`${PROXY_URL}/v1/agent/permissions`, { method: "GET", headers: {} });
     }
     catch (err) {
         return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
@@ -319,7 +258,7 @@ async function handleListPlatforms() {
     return { content: [{ type: "text", text: body }] };
 }
 async function handleUsePlatform(params) {
-    if (AGENT_PRIVATE_KEY_RAW === "PENDING_FIRST_CALL") {
+    if (AGENT_PRIVATE_KEY_RAW === null) {
         await notifyBindSecret();
         return pendingFirstCallResponse();
     }
@@ -332,7 +271,7 @@ async function handleUsePlatform(params) {
     };
     let response;
     try {
-        response = await bearerFetch(`${PROXY_URL}/v1/actions`, {
+        response = await fetchWithAuth(`${PROXY_URL}/v1/actions`, {
             method: "POST",
             body: JSON.stringify(requestBody),
         });
@@ -378,23 +317,6 @@ async function handleAgentStatus(token) {
         return errorContent(`Proxy error ${response.status}: ${body}`);
     return { content: [{ type: "text", text: body }] };
 }
-async function handleAgentPermissions() {
-    if (AGENT_PRIVATE_KEY_RAW === "PENDING_FIRST_CALL") {
-        await notifyBindSecret();
-        return pendingFirstCallResponse();
-    }
-    let response;
-    try {
-        response = await bearerFetch(`${PROXY_URL}/v1/agent/permissions`, { method: "GET", headers: {} });
-    }
-    catch (err) {
-        return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
-    }
-    const body = await response.text();
-    if (!response.ok)
-        return errorContent(`Proxy error ${response.status}: ${body}`);
-    return { content: [{ type: "text", text: body }] };
-}
 async function handleAuthzenEvaluate(platformId, scope) {
     const authzenBody = {
         subject: { type: "agent", id: AGENT_ID },
@@ -417,28 +339,15 @@ async function handleAuthzenEvaluate(platformId, scope) {
         return errorContent(`Proxy error ${response.status}: ${body}`);
     return { content: [{ type: "text", text: body }] };
 }
-async function handleIntentResolve(intent, context) {
-    const requestBody = { intent };
-    if (context !== undefined)
-        requestBody.context = context;
-    let response;
-    try {
-        response = await fetchWithTimeout(`${PROXY_URL}/v1/intent/resolve`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(requestBody),
-        });
-    }
-    catch (err) {
-        return errorContent(`Network error: ${err instanceof Error ? err.message : err}`);
-    }
-    const body = await response.text();
-    if (!response.ok)
-        return errorContent(`Proxy error ${response.status}: ${body}`);
-    return { content: [{ type: "text", text: body }] };
-}
 // ---------------------------------------------------------------------------
 // Connect transport
 // ---------------------------------------------------------------------------
-const transport = new StdioServerTransport();
-await server.connect(transport);
+if (process.env.MCP_TRANSPORT === "http") {
+    const { startHttpTransport } = await import("./transports/http.js");
+    const port = parseInt(process.env.MCP_PORT ?? "3100", 10);
+    await startHttpTransport(server, port);
+}
+else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/pem.js

@@ -0,0 +1,34 @@
+import { readFileSync } from "fs";
+/**
+ * Reads the RS256 private key from environment variables, supporting four formats:
+ * - AGENT_PRIVATE_KEY_B64: base64-encoded PEM
+ * - AGENT_PRIVATE_KEY_PATH: path to a PEM file
+ * - AGENT_PRIVATE_KEY: raw multi-line PEM or \n-escaped single-line PEM
+ */
+export function readPrivateKeyFromEnv() {
+    // 1. Base64-encoded PEM
+    if (process.env.AGENT_PRIVATE_KEY_B64) {
+        return Buffer.from(process.env.AGENT_PRIVATE_KEY_B64, "base64").toString("utf-8").trim();
+    }
+    // 2. Path to PEM file
+    if (process.env.AGENT_PRIVATE_KEY_PATH) {
+        try {
+            return readFileSync(process.env.AGENT_PRIVATE_KEY_PATH, "utf-8").trim();
+        }
+        catch (err) {
+            throw new Error(`Cannot read AGENT_PRIVATE_KEY_PATH: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // 3. Raw PEM content (multi-line or \n-escaped)
+    if (process.env.AGENT_PRIVATE_KEY) {
+        const raw = process.env.AGENT_PRIVATE_KEY.trim();
+        // Unescape \n sequences
+        const unescaped = raw.replace(/\\n/g, "\n");
+        // Wrap bare base64 blob without headers
+        if (!unescaped.startsWith("-----")) {
+            return `-----BEGIN PRIVATE KEY-----\n${unescaped}\n-----END PRIVATE KEY-----`;
+        }
+        return unescaped;
+    }
+    throw new Error("No private key provided. Set AGENT_PRIVATE_KEY, AGENT_PRIVATE_KEY_PATH, or AGENT_PRIVATE_KEY_B64.");
+}

package/dist/transports/http.js

@@ -0,0 +1,38 @@
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+export async function startHttpTransport(server, port) {
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    const httpServer = createServer(async (req, res) => {
+        try {
+            await transport.handleRequest(req, res, await readBody(req));
+        }
+        catch (err) {
+            res.writeHead(500);
+            res.end(JSON.stringify({ error: "Internal server error" }));
+        }
+    });
+    await server.connect(transport);
+    httpServer.listen(port, () => {
+        process.stderr.write(`[mcp-server] HTTP transport listening on port ${port}\n`);
+    });
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf-8");
+            if (!raw) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                resolve(undefined);
+            }
+        });
+        req.on("error", reject);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "AgentValet MCP server — lets AI agents call approved platforms via the AgentValet proxy",
   "type": "module",
   "main": "dist/index.js",