@ardensh/mcp 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @ardensh/mcp
+
+MCP server for managing [Arden](https://arden.sh) AI agent spend controls. Lets Claude Desktop, Cursor, Claude Code, and other MCP-compatible AI clients provision and manage Arden agents via natural language.
+
+> npm package: `@ardensh/mcp`
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `arden_provision_agent` | Create a new agent with budget limits and vendor restrictions |
+| `arden_list_agents` | List all agents with budget usage |
+| `arden_agent_status` | Detailed status and budget breakdown for a specific agent |
+| `arden_update_agent` | Update an agent's budgets, allowed vendors, or status |
+| `arden_fund_agent` | Get wallet address and USDC funding instructions |
+
+## Prerequisites
+
+Install the Arden CLI and log in to generate your API key:
+
+```bash
+npm install -g @arden/cli
+arden login
+```
+
+This writes your API key to `~/.arden/config.json`, which the MCP server reads automatically. You can skip the `ARDEN_API_KEY` env var if you've already done this.
+
+## Usage with Claude Desktop
+
+Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "arden": {
+      "command": "npx",
+      "args": ["-y", "@ardensh/mcp"],
+      "env": {
+        "ARDEN_API_KEY": "arden_live_..."
+      }
+    }
+  }
+}
+```
+
+`ARDEN_API_KEY` is optional if you have already run `arden login` on the same machine.
+
+## Usage with Claude Code
+
+```bash
+claude mcp add arden npx -y @ardensh/mcp
+```
+
+If you haven't run `arden login`, pass your key via env:
+
+```bash
+claude mcp add arden -e ARDEN_API_KEY=arden_live_... npx -y @ardensh/mcp
+```
+
+## Usage with Cursor
+
+Add the same block as the Claude Desktop config above to your Cursor MCP settings under **Settings → MCP**.
+
+## Authentication
+
+The server looks for credentials in this order:
+
+1. `ARDEN_API_KEY` environment variable
+2. `~/.arden/config.json` (written by `arden login`)
+
+If neither is found, tool calls return a clear error message rather than crashing.
+
+## Development
+
+```bash
+npm install
+npm run dev      # run with tsx (no build step)
+npm run build    # compile to dist/
+```

package/dist/auth.d.ts

@@ -0,0 +1,3 @@
+export declare function getApiKey(): string;
+export declare const API_BASE = "https://ir7hdqp3ei.execute-api.us-east-1.amazonaws.com/prod";
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,14 @@
+import Conf from 'conf';
+import os from 'os';
+const store = new Conf({ projectName: 'arden', cwd: os.homedir() + '/.arden' });
+export function getApiKey() {
+    const fromEnv = process.env.ARDEN_API_KEY;
+    if (fromEnv)
+        return fromEnv;
+    const fromConfig = store.get('apiKey');
+    if (fromConfig)
+        return fromConfig;
+    throw new Error('Not authenticated. Set ARDEN_API_KEY or run `arden login`.');
+}
+export const API_BASE = 'https://ir7hdqp3ei.execute-api.us-east-1.amazonaws.com/prod';
+//# sourceMappingURL=auth.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { provisionAgent } from './tools/provision.js';
+import { listAgents } from './tools/list.js';
+import { agentStatus } from './tools/status.js';
+import { fundAgent } from './tools/fund.js';
+import { updateAgent } from './tools/update.js';
+const server = new McpServer({
+    name: 'arden',
+    version: '0.1.0',
+});
+server.tool('arden_provision_agent', 'Provision a new Arden AI agent with spend controls and vendor restrictions', {
+    name: z.string().describe('Agent name: 3-50 chars, alphanumeric + hyphens only'),
+    monthly_budget: z.number().optional().describe('Monthly spend budget in USD'),
+    daily_budget: z.number().optional().describe('Daily spend budget in USD'),
+    weekly_budget: z.number().optional().describe('Weekly spend budget in USD'),
+    per_transaction_limit: z.number().optional().describe('Per-transaction spend limit in USD'),
+    allowed_vendors: z
+        .string()
+        .describe('Comma-separated vendor domains, or "*" for all vendors'),
+}, async (input) => {
+    const text = await provisionAgent(input);
+    return { content: [{ type: 'text', text }] };
+});
+server.tool('arden_list_agents', 'List all Arden agents with their status and budget usage', {}, async () => {
+    const text = await listAgents();
+    return { content: [{ type: 'text', text }] };
+});
+server.tool('arden_agent_status', 'Get detailed status and budget breakdown for a specific Arden agent', {
+    name: z.string().describe('Name of the agent to inspect'),
+}, async ({ name }) => {
+    const text = await agentStatus(name);
+    return { content: [{ type: 'text', text }] };
+});
+server.tool('arden_fund_agent', 'Get wallet address and funding instructions for an Arden agent', {
+    name: z.string().describe('Name of the agent to fund'),
+}, async ({ name }) => {
+    const text = await fundAgent(name);
+    return { content: [{ type: 'text', text }] };
+});
+server.tool('arden_update_agent', "Update an existing agent's budget limits, allowed vendors, or status", {
+    name: z.string().describe('Name of the agent to update'),
+    monthly_budget: z.number().optional().describe('New monthly budget in USD'),
+    daily_budget: z.number().optional().describe('New daily budget in USD'),
+    weekly_budget: z.number().optional().describe('New weekly budget in USD'),
+    per_transaction_limit: z.number().optional().describe('New per-transaction limit in USD'),
+    allowed_vendors: z.string().optional().describe('Comma-separated vendor domains, or "*" for all'),
+    status: z.enum(['active', 'paused']).optional().describe('Set agent status to active or paused'),
+}, async (input) => {
+    const text = await updateAgent(input);
+    return { content: [{ type: 'text', text }] };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/dist/tools/fund.d.ts

@@ -0,0 +1,2 @@
+export declare function fundAgent(name: string): Promise<string>;
+//# sourceMappingURL=fund.d.ts.map

package/dist/tools/fund.js

@@ -0,0 +1,35 @@
+import axios from 'axios';
+import { getApiKey, API_BASE } from '../auth.js';
+export async function fundAgent(name) {
+    const apiKey = getApiKey();
+    try {
+        const { data } = await axios.get(`${API_BASE}/agents/${encodeURIComponent(name)}`, {
+            headers: { 'X-API-Key': apiKey },
+        });
+        const wallet = data.wallet_address;
+        if (!wallet) {
+            return `Agent "${name}" does not have a wallet address yet.`;
+        }
+        return [
+            `Funding instructions for agent "${name}":`,
+            '',
+            `Wallet address: ${wallet}`,
+            '',
+            'To fund this agent:',
+            '  1. Send USDC to the wallet address above.',
+            '  2. Network: Base mainnet (chain ID 8453).',
+            '  3. Token: USDC (native USDC on Base, not bridged).',
+            '',
+            'The agent will use this wallet for x402 payments when making API calls on your behalf.',
+            'Funds are available immediately after the transaction is confirmed on-chain.',
+        ].join('\n');
+    }
+    catch (err) {
+        if (axios.isAxiosError(err)) {
+            const body = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+            return `Failed to retrieve agent wallet: ${body}`;
+        }
+        return `Failed to retrieve agent wallet: ${String(err)}`;
+    }
+}
+//# sourceMappingURL=fund.js.map

package/dist/tools/list.d.ts

@@ -0,0 +1,2 @@
+export declare function listAgents(): Promise<string>;
+//# sourceMappingURL=list.d.ts.map

package/dist/tools/list.js

@@ -0,0 +1,38 @@
+import axios from 'axios';
+import { getApiKey, API_BASE } from '../auth.js';
+export async function listAgents() {
+    const apiKey = getApiKey();
+    try {
+        const { data } = await axios.get(`${API_BASE}/agents`, {
+            headers: { 'X-API-Key': apiKey },
+        });
+        const agents = Array.isArray(data) ? data : data.agents ?? [];
+        if (agents.length === 0) {
+            return 'No agents found. Use arden_provision_agent to create one.';
+        }
+        const lines = agents.map((agent) => {
+            const spent = agent.spent_this_month ?? 0;
+            const budget = agent.monthly_budget;
+            const remaining = budget !== undefined ? budget - spent : undefined;
+            const pct = budget !== undefined && budget > 0 ? ((spent / budget) * 100).toFixed(1) + '%' : 'N/A';
+            return [
+                `Name:            ${agent.name}`,
+                `Status:          ${agent.status}`,
+                `Monthly budget:  ${budget !== undefined ? '$' + budget : 'N/A'}`,
+                `Spent this month: $${spent}`,
+                `Remaining:       ${remaining !== undefined ? '$' + remaining : 'N/A'}`,
+                `% Used:          ${pct}`,
+                `Wallet:          ${agent.wallet_address ?? 'N/A'}`,
+            ].join('\n');
+        });
+        return lines.join('\n\n---\n\n');
+    }
+    catch (err) {
+        if (axios.isAxiosError(err)) {
+            const body = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+            return `Failed to list agents: ${body}`;
+        }
+        return `Failed to list agents: ${String(err)}`;
+    }
+}
+//# sourceMappingURL=list.js.map

package/dist/tools/provision.d.ts

@@ -0,0 +1,38 @@
+export declare const provisionAgentSchema: {
+    name: {
+        type: "string";
+        description: string;
+    };
+    monthly_budget: {
+        type: "number";
+        description: string;
+    };
+    daily_budget: {
+        type: "number";
+        description: string;
+    };
+    weekly_budget: {
+        type: "number";
+        description: string;
+    };
+    per_transaction_limit: {
+        type: "number";
+        description: string;
+    };
+    allowed_vendors: {
+        type: "string";
+        description: string;
+    };
+};
+export declare const provisionAgentRequired: readonly ["name", "allowed_vendors"];
+interface ProvisionInput {
+    name: string;
+    monthly_budget?: number;
+    daily_budget?: number;
+    weekly_budget?: number;
+    per_transaction_limit?: number;
+    allowed_vendors: string;
+}
+export declare function provisionAgent(input: ProvisionInput): Promise<string>;
+export {};
+//# sourceMappingURL=provision.d.ts.map

package/dist/tools/provision.js

@@ -0,0 +1,51 @@
+import axios from 'axios';
+import { getApiKey, API_BASE } from '../auth.js';
+export const provisionAgentSchema = {
+    name: { type: 'string', description: 'Agent name: 3-50 chars, alphanumeric + hyphens only' },
+    monthly_budget: { type: 'number', description: 'Monthly spend budget in USD' },
+    daily_budget: { type: 'number', description: 'Daily spend budget in USD' },
+    weekly_budget: { type: 'number', description: 'Weekly spend budget in USD' },
+    per_transaction_limit: { type: 'number', description: 'Per-transaction spend limit in USD' },
+    allowed_vendors: { type: 'string', description: 'Comma-separated vendor domains, or "*" for all vendors' },
+};
+export const provisionAgentRequired = ['name', 'allowed_vendors'];
+export async function provisionAgent(input) {
+    const { name, monthly_budget, daily_budget, weekly_budget, per_transaction_limit, allowed_vendors } = input;
+    if (!/^[a-zA-Z0-9-]{3,50}$/.test(name)) {
+        return 'Invalid agent name. Must be 3-50 characters, alphanumeric and hyphens only.';
+    }
+    if (!monthly_budget && !daily_budget && !weekly_budget) {
+        return 'At least one budget field is required: monthly_budget, daily_budget, or weekly_budget.';
+    }
+    const apiKey = getApiKey();
+    const body = { name, allowed_vendors };
+    if (monthly_budget !== undefined)
+        body.monthly_budget = monthly_budget;
+    if (daily_budget !== undefined)
+        body.daily_budget = daily_budget;
+    if (weekly_budget !== undefined)
+        body.weekly_budget = weekly_budget;
+    if (per_transaction_limit !== undefined)
+        body.per_transaction_limit = per_transaction_limit;
+    try {
+        const { data } = await axios.post(`${API_BASE}/agents`, body, {
+            headers: { 'X-API-Key': apiKey },
+        });
+        const { wallet_address, agent_key } = data;
+        return [
+            `Agent "${name}" provisioned successfully.`,
+            `Wallet address: ${wallet_address}`,
+            `Agent API key: ${agent_key}`,
+            '',
+            'IMPORTANT: Save the agent API key — it will not be shown again.',
+        ].join('\n');
+    }
+    catch (err) {
+        if (axios.isAxiosError(err)) {
+            const body = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+            return `Failed to provision agent: ${body}`;
+        }
+        return `Failed to provision agent: ${String(err)}`;
+    }
+}
+//# sourceMappingURL=provision.js.map

package/dist/tools/status.d.ts

@@ -0,0 +1,2 @@
+export declare function agentStatus(name: string): Promise<string>;
+//# sourceMappingURL=status.d.ts.map

package/dist/tools/status.js

@@ -0,0 +1,43 @@
+import axios from 'axios';
+import { getApiKey, API_BASE } from '../auth.js';
+function formatBudgetWindow(label, window) {
+    if (!window)
+        return `${label}: not set`;
+    const limit = window.limit !== undefined ? '$' + window.limit : 'N/A';
+    const spent = window.spent !== undefined ? '$' + window.spent : '$0';
+    const remaining = window.limit !== undefined && window.spent !== undefined
+        ? '$' + (window.limit - window.spent)
+        : 'N/A';
+    const pct = window.limit !== undefined && window.limit > 0 && window.spent !== undefined
+        ? ((window.spent / window.limit) * 100).toFixed(1) + '%'
+        : 'N/A';
+    return `${label}: limit=${limit}, spent=${spent}, remaining=${remaining}, used=${pct}`;
+}
+export async function agentStatus(name) {
+    const apiKey = getApiKey();
+    try {
+        const { data } = await axios.get(`${API_BASE}/agents/${encodeURIComponent(name)}`, {
+            headers: { 'X-API-Key': apiKey },
+        });
+        return [
+            `Agent: ${data.name}`,
+            `Status: ${data.status}`,
+            `Wallet: ${data.wallet_address ?? 'N/A'}`,
+            `Allowed vendors: ${data.allowed_vendors ?? 'N/A'}`,
+            '',
+            'Budget windows:',
+            '  ' + formatBudgetWindow('Monthly', data.monthly),
+            '  ' + formatBudgetWindow('Daily', data.daily),
+            '  ' + formatBudgetWindow('Weekly', data.weekly),
+            `  Per-transaction limit: ${data.per_transaction_limit !== undefined ? '$' + data.per_transaction_limit : 'not set'}`,
+        ].join('\n');
+    }
+    catch (err) {
+        if (axios.isAxiosError(err)) {
+            const body = err.response?.data ? JSON.stringify(err.response.data) : err.message;
+            return `Failed to get agent status: ${body}`;
+        }
+        return `Failed to get agent status: ${String(err)}`;
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/tools/update.d.ts

@@ -0,0 +1,12 @@
+interface UpdateInput {
+    name: string;
+    monthly_budget?: number;
+    daily_budget?: number;
+    weekly_budget?: number;
+    per_transaction_limit?: number;
+    allowed_vendors?: string;
+    status?: string;
+}
+export declare function updateAgent(input: UpdateInput): Promise<string>;
+export {};
+//# sourceMappingURL=update.d.ts.map

package/dist/tools/update.js

@@ -0,0 +1,46 @@
+import axios from 'axios';
+import { getApiKey, API_BASE } from '../auth.js';
+export async function updateAgent(input) {
+    const { name, monthly_budget, daily_budget, weekly_budget, per_transaction_limit, allowed_vendors, status } = input;
+    const body = {};
+    if (monthly_budget !== undefined)
+        body.monthly_budget = monthly_budget;
+    if (daily_budget !== undefined)
+        body.daily_budget = daily_budget;
+    if (weekly_budget !== undefined)
+        body.weekly_budget = weekly_budget;
+    if (per_transaction_limit !== undefined)
+        body.per_transaction_limit = per_transaction_limit;
+    if (allowed_vendors !== undefined)
+        body.allowed_vendors = allowed_vendors;
+    if (status !== undefined)
+        body.status = status;
+    if (Object.keys(body).length === 0) {
+        return 'Provide at least one field to update.';
+    }
+    const apiKey = getApiKey();
+    try {
+        await axios.patch(`${API_BASE}/agents/${encodeURIComponent(name)}`, body, {
+            headers: { 'X-API-Key': apiKey },
+        });
+        const changed = Object.entries(body)
+            .map(([k, v]) => `  ${k}: ${v}`)
+            .join('\n');
+        return `Agent "${name}" updated successfully:\n${changed}`;
+    }
+    catch (err) {
+        if (axios.isAxiosError(err)) {
+            const status = err.response?.status;
+            const data = err.response?.data;
+            if (status === 404)
+                return `Agent '${name}' not found.`;
+            if (status === 400)
+                return `Bad request: ${typeof data === 'object' ? JSON.stringify(data) : data ?? err.message}`;
+            if (status === 401 || status === 403)
+                return 'Not authenticated. Set ARDEN_API_KEY or run `arden login`.';
+            return `Failed to update agent: ${typeof data === 'object' ? JSON.stringify(data) : data ?? err.message}`;
+        }
+        return `Failed to update agent: ${String(err)}`;
+    }
+}
+//# sourceMappingURL=update.js.map

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ardensh/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for managing Arden AI agent spend controls",
+  "type": "module",
+  "bin": {
+    "arden-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0",
+    "conf": "^13.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "tsx": "^4.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,14 @@
+import Conf from 'conf'
+import os from 'os'
+
+const store = new Conf({ projectName: 'arden', cwd: os.homedir() + '/.arden' })
+
+export function getApiKey(): string {
+  const fromEnv = process.env.ARDEN_API_KEY
+  if (fromEnv) return fromEnv
+  const fromConfig = store.get('apiKey') as string | undefined
+  if (fromConfig) return fromConfig
+  throw new Error('Not authenticated. Set ARDEN_API_KEY or run `arden login`.')
+}
+
+export const API_BASE = 'https://ir7hdqp3ei.execute-api.us-east-1.amazonaws.com/prod'

package/src/index.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { provisionAgent } from './tools/provision.js'
+import { listAgents } from './tools/list.js'
+import { agentStatus } from './tools/status.js'
+import { fundAgent } from './tools/fund.js'
+import { updateAgent } from './tools/update.js'
+
+const server = new McpServer({
+  name: 'arden',
+  version: '0.1.0',
+})
+
+server.tool(
+  'arden_provision_agent',
+  'Provision a new Arden AI agent with spend controls and vendor restrictions',
+  {
+    name: z.string().describe('Agent name: 3-50 chars, alphanumeric + hyphens only'),
+    monthly_budget: z.number().optional().describe('Monthly spend budget in USD'),
+    daily_budget: z.number().optional().describe('Daily spend budget in USD'),
+    weekly_budget: z.number().optional().describe('Weekly spend budget in USD'),
+    per_transaction_limit: z.number().optional().describe('Per-transaction spend limit in USD'),
+    allowed_vendors: z
+      .string()
+      .describe('Comma-separated vendor domains, or "*" for all vendors'),
+  },
+  async (input) => {
+    const text = await provisionAgent(input)
+    return { content: [{ type: 'text', text }] }
+  }
+)
+
+server.tool(
+  'arden_list_agents',
+  'List all Arden agents with their status and budget usage',
+  {},
+  async () => {
+    const text = await listAgents()
+    return { content: [{ type: 'text', text }] }
+  }
+)
+
+server.tool(
+  'arden_agent_status',
+  'Get detailed status and budget breakdown for a specific Arden agent',
+  {
+    name: z.string().describe('Name of the agent to inspect'),
+  },
+  async ({ name }) => {
+    const text = await agentStatus(name)
+    return { content: [{ type: 'text', text }] }
+  }
+)
+
+server.tool(
+  'arden_fund_agent',
+  'Get wallet address and funding instructions for an Arden agent',
+  {
+    name: z.string().describe('Name of the agent to fund'),
+  },
+  async ({ name }) => {
+    const text = await fundAgent(name)
+    return { content: [{ type: 'text', text }] }
+  }
+)
+
+server.tool(
+  'arden_update_agent',
+  "Update an existing agent's budget limits, allowed vendors, or status",
+  {
+    name: z.string().describe('Name of the agent to update'),
+    monthly_budget: z.number().optional().describe('New monthly budget in USD'),
+    daily_budget: z.number().optional().describe('New daily budget in USD'),
+    weekly_budget: z.number().optional().describe('New weekly budget in USD'),
+    per_transaction_limit: z.number().optional().describe('New per-transaction limit in USD'),
+    allowed_vendors: z.string().optional().describe('Comma-separated vendor domains, or "*" for all'),
+    status: z.enum(['active', 'paused']).optional().describe('Set agent status to active or paused'),
+  },
+  async (input) => {
+    const text = await updateAgent(input)
+    return { content: [{ type: 'text', text }] }
+  }
+)
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/src/tools/fund.ts

@@ -0,0 +1,42 @@
+import axios from 'axios'
+import { getApiKey, API_BASE } from '../auth.js'
+
+interface AgentDetail {
+  wallet_address?: string
+  [key: string]: unknown
+}
+
+export async function fundAgent(name: string): Promise<string> {
+  const apiKey = getApiKey()
+
+  try {
+    const { data } = await axios.get<AgentDetail>(`${API_BASE}/agents/${encodeURIComponent(name)}`, {
+      headers: { 'X-API-Key': apiKey },
+    })
+
+    const wallet = data.wallet_address
+    if (!wallet) {
+      return `Agent "${name}" does not have a wallet address yet.`
+    }
+
+    return [
+      `Funding instructions for agent "${name}":`,
+      '',
+      `Wallet address: ${wallet}`,
+      '',
+      'To fund this agent:',
+      '  1. Send USDC to the wallet address above.',
+      '  2. Network: Base mainnet (chain ID 8453).',
+      '  3. Token: USDC (native USDC on Base, not bridged).',
+      '',
+      'The agent will use this wallet for x402 payments when making API calls on your behalf.',
+      'Funds are available immediately after the transaction is confirmed on-chain.',
+    ].join('\n')
+  } catch (err) {
+    if (axios.isAxiosError(err)) {
+      const body = err.response?.data ? JSON.stringify(err.response.data) : err.message
+      return `Failed to retrieve agent wallet: ${body}`
+    }
+    return `Failed to retrieve agent wallet: ${String(err)}`
+  }
+}

package/src/tools/list.ts

@@ -0,0 +1,53 @@
+import axios from 'axios'
+import { getApiKey, API_BASE } from '../auth.js'
+
+interface Agent {
+  name: string
+  status: string
+  monthly_budget?: number
+  spent_this_month?: number
+  wallet_address?: string
+  [key: string]: unknown
+}
+
+export async function listAgents(): Promise<string> {
+  const apiKey = getApiKey()
+
+  try {
+    const { data } = await axios.get<Agent[]>(`${API_BASE}/agents`, {
+      headers: { 'X-API-Key': apiKey },
+    })
+
+    const agents: Agent[] = Array.isArray(data) ? data : (data as { agents?: Agent[] }).agents ?? []
+
+    if (agents.length === 0) {
+      return 'No agents found. Use arden_provision_agent to create one.'
+    }
+
+    const lines = agents.map((agent) => {
+      const spent = agent.spent_this_month ?? 0
+      const budget = agent.monthly_budget
+      const remaining = budget !== undefined ? budget - spent : undefined
+      const pct =
+        budget !== undefined && budget > 0 ? ((spent / budget) * 100).toFixed(1) + '%' : 'N/A'
+
+      return [
+        `Name:            ${agent.name}`,
+        `Status:          ${agent.status}`,
+        `Monthly budget:  ${budget !== undefined ? '$' + budget : 'N/A'}`,
+        `Spent this month: $${spent}`,
+        `Remaining:       ${remaining !== undefined ? '$' + remaining : 'N/A'}`,
+        `% Used:          ${pct}`,
+        `Wallet:          ${agent.wallet_address ?? 'N/A'}`,
+      ].join('\n')
+    })
+
+    return lines.join('\n\n---\n\n')
+  } catch (err) {
+    if (axios.isAxiosError(err)) {
+      const body = err.response?.data ? JSON.stringify(err.response.data) : err.message
+      return `Failed to list agents: ${body}`
+    }
+    return `Failed to list agents: ${String(err)}`
+  }
+}

package/src/tools/provision.ts

@@ -0,0 +1,63 @@
+import axios from 'axios'
+import { getApiKey, API_BASE } from '../auth.js'
+
+export const provisionAgentSchema = {
+  name: { type: 'string' as const, description: 'Agent name: 3-50 chars, alphanumeric + hyphens only' },
+  monthly_budget: { type: 'number' as const, description: 'Monthly spend budget in USD' },
+  daily_budget: { type: 'number' as const, description: 'Daily spend budget in USD' },
+  weekly_budget: { type: 'number' as const, description: 'Weekly spend budget in USD' },
+  per_transaction_limit: { type: 'number' as const, description: 'Per-transaction spend limit in USD' },
+  allowed_vendors: { type: 'string' as const, description: 'Comma-separated vendor domains, or "*" for all vendors' },
+}
+
+export const provisionAgentRequired = ['name', 'allowed_vendors'] as const
+
+interface ProvisionInput {
+  name: string
+  monthly_budget?: number
+  daily_budget?: number
+  weekly_budget?: number
+  per_transaction_limit?: number
+  allowed_vendors: string
+}
+
+export async function provisionAgent(input: ProvisionInput): Promise<string> {
+  const { name, monthly_budget, daily_budget, weekly_budget, per_transaction_limit, allowed_vendors } = input
+
+  if (!/^[a-zA-Z0-9-]{3,50}$/.test(name)) {
+    return 'Invalid agent name. Must be 3-50 characters, alphanumeric and hyphens only.'
+  }
+
+  if (!monthly_budget && !daily_budget && !weekly_budget) {
+    return 'At least one budget field is required: monthly_budget, daily_budget, or weekly_budget.'
+  }
+
+  const apiKey = getApiKey()
+
+  const body: Record<string, unknown> = { name, allowed_vendors }
+  if (monthly_budget !== undefined) body.monthly_budget = monthly_budget
+  if (daily_budget !== undefined) body.daily_budget = daily_budget
+  if (weekly_budget !== undefined) body.weekly_budget = weekly_budget
+  if (per_transaction_limit !== undefined) body.per_transaction_limit = per_transaction_limit
+
+  try {
+    const { data } = await axios.post(`${API_BASE}/agents`, body, {
+      headers: { 'X-API-Key': apiKey },
+    })
+
+    const { wallet_address, agent_key } = data
+    return [
+      `Agent "${name}" provisioned successfully.`,
+      `Wallet address: ${wallet_address}`,
+      `Agent API key: ${agent_key}`,
+      '',
+      'IMPORTANT: Save the agent API key — it will not be shown again.',
+    ].join('\n')
+  } catch (err) {
+    if (axios.isAxiosError(err)) {
+      const body = err.response?.data ? JSON.stringify(err.response.data) : err.message
+      return `Failed to provision agent: ${body}`
+    }
+    return `Failed to provision agent: ${String(err)}`
+  }
+}

package/src/tools/status.ts

@@ -0,0 +1,63 @@
+import axios from 'axios'
+import { getApiKey, API_BASE } from '../auth.js'
+
+interface Budget {
+  limit?: number
+  spent?: number
+}
+
+interface AgentDetail {
+  name: string
+  status: string
+  wallet_address?: string
+  allowed_vendors?: string
+  monthly?: Budget
+  daily?: Budget
+  weekly?: Budget
+  per_transaction_limit?: number
+  [key: string]: unknown
+}
+
+function formatBudgetWindow(label: string, window?: Budget): string {
+  if (!window) return `${label}: not set`
+  const limit = window.limit !== undefined ? '$' + window.limit : 'N/A'
+  const spent = window.spent !== undefined ? '$' + window.spent : '$0'
+  const remaining =
+    window.limit !== undefined && window.spent !== undefined
+      ? '$' + (window.limit - window.spent)
+      : 'N/A'
+  const pct =
+    window.limit !== undefined && window.limit > 0 && window.spent !== undefined
+      ? ((window.spent / window.limit) * 100).toFixed(1) + '%'
+      : 'N/A'
+  return `${label}: limit=${limit}, spent=${spent}, remaining=${remaining}, used=${pct}`
+}
+
+export async function agentStatus(name: string): Promise<string> {
+  const apiKey = getApiKey()
+
+  try {
+    const { data } = await axios.get<AgentDetail>(`${API_BASE}/agents/${encodeURIComponent(name)}`, {
+      headers: { 'X-API-Key': apiKey },
+    })
+
+    return [
+      `Agent: ${data.name}`,
+      `Status: ${data.status}`,
+      `Wallet: ${data.wallet_address ?? 'N/A'}`,
+      `Allowed vendors: ${data.allowed_vendors ?? 'N/A'}`,
+      '',
+      'Budget windows:',
+      '  ' + formatBudgetWindow('Monthly', data.monthly),
+      '  ' + formatBudgetWindow('Daily', data.daily),
+      '  ' + formatBudgetWindow('Weekly', data.weekly),
+      `  Per-transaction limit: ${data.per_transaction_limit !== undefined ? '$' + data.per_transaction_limit : 'not set'}`,
+    ].join('\n')
+  } catch (err) {
+    if (axios.isAxiosError(err)) {
+      const body = err.response?.data ? JSON.stringify(err.response.data) : err.message
+      return `Failed to get agent status: ${body}`
+    }
+    return `Failed to get agent status: ${String(err)}`
+  }
+}

package/src/tools/update.ts

@@ -0,0 +1,51 @@
+import axios from 'axios'
+import { getApiKey, API_BASE } from '../auth.js'
+
+interface UpdateInput {
+  name: string
+  monthly_budget?: number
+  daily_budget?: number
+  weekly_budget?: number
+  per_transaction_limit?: number
+  allowed_vendors?: string
+  status?: string
+}
+
+export async function updateAgent(input: UpdateInput): Promise<string> {
+  const { name, monthly_budget, daily_budget, weekly_budget, per_transaction_limit, allowed_vendors, status } = input
+
+  const body: Record<string, unknown> = {}
+  if (monthly_budget !== undefined) body.monthly_budget = monthly_budget
+  if (daily_budget !== undefined) body.daily_budget = daily_budget
+  if (weekly_budget !== undefined) body.weekly_budget = weekly_budget
+  if (per_transaction_limit !== undefined) body.per_transaction_limit = per_transaction_limit
+  if (allowed_vendors !== undefined) body.allowed_vendors = allowed_vendors
+  if (status !== undefined) body.status = status
+
+  if (Object.keys(body).length === 0) {
+    return 'Provide at least one field to update.'
+  }
+
+  const apiKey = getApiKey()
+
+  try {
+    await axios.patch(`${API_BASE}/agents/${encodeURIComponent(name)}`, body, {
+      headers: { 'X-API-Key': apiKey },
+    })
+
+    const changed = Object.entries(body)
+      .map(([k, v]) => `  ${k}: ${v}`)
+      .join('\n')
+    return `Agent "${name}" updated successfully:\n${changed}`
+  } catch (err) {
+    if (axios.isAxiosError(err)) {
+      const status = err.response?.status
+      const data = err.response?.data
+      if (status === 404) return `Agent '${name}' not found.`
+      if (status === 400) return `Bad request: ${typeof data === 'object' ? JSON.stringify(data) : data ?? err.message}`
+      if (status === 401 || status === 403) return 'Not authenticated. Set ARDEN_API_KEY or run `arden login`.'
+      return `Failed to update agent: ${typeof data === 'object' ? JSON.stringify(data) : data ?? err.message}`
+    }
+    return `Failed to update agent: ${String(err)}`
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}