ogment 0.2.3 → 0.2.4

package/README.md

@@ -18,9 +18,9 @@ Without a control plane, you're either giving every AI client raw API keys (inse
 - **Connect anything** — SaaS tools (Salesforce, Slack, Notion), internal APIs, databases, data warehouses
 - **Enterprise SSO** — Okta, Azure AD, Google Workspace — federated auth across your organization
 - **Integration marketplace** — 300+ pre-built connectors, community-contributed, security-scanned
+- **Per-agent permissions** — control which servers each agent can access, with public and restricted servers
 - **Agent approval flows** — human-in-the-loop for sensitive operations, per-tool granular permissions
-- **Full audit trail** — every tool call logged, searchable, and exportable
-- **Works for agents and humans** — CLI for agents via exec, dashboard for humans, API for custom backends
+- **Full audit trail** — every tool call logged per agent, searchable, and exportable
 - **Portable across AI clients** — Cursor, OpenClaw, Claude Desktop, ChatGPT, or your own agents — same config, same permissions
 
 ## How It Works
@@ -29,19 +29,19 @@ Without a control plane, you're either giving every AI client raw API keys (inse
 Any AI Client
 (OpenClaw, Cursor, Claude, ChatGPT, custom agents)
     │
-    │  ogment call <server> <tool> <args>
+    │  ogment --agentId <id> call <server> <tool> <args>
     ▼
 ┌─────────────────────────────────────────┐
 │            Ogment Platform              │
 │                                         │
 │  ✓ Authenticate (OAuth, SSO, tokens)    │
+│  ✓ Identify agent + enforce permissions │
 │  ✓ Portable workflows (MCP, Skills,     │
 │    Claude Plugins) — author once,       │
 │    deploy to any AI client              │
-│  ✓ Enforce permissions per tool         │
 │  ✓ Human approval for sensitive ops     │
 │  ✓ Inject real credentials server-side  │
-│  ✓ Log every call for audit             │
+│  ✓ Log every call per agent for audit   │
 └──────────────┬──────────────────────────┘
                │
     ┌──────────┼──────────┐
@@ -58,42 +58,49 @@ npm install -g ogment
 
 **`ogment login`** — Authenticate via browser OAuth. Auto-discovers your orgs and servers.
 
-**`ogment servers [path]`** — List all servers, or inspect a specific server's tools:
-```
-ogment servers · ogment servers salesforce · ogment servers --json
-```
+**`ogment --agentId <id> servers`** — List servers the agent has access to. Shows descriptions, tool counts.
 
-**`ogment call <server> <tool> [args]`** — Call any tool. Returns JSON:
-```
-ogment call salesforce query_accounts '{"limit":5}'
-ogment call my-api get_customers '{"status":"active"}'
+**`ogment --agentId <id> servers <path>`** — Inspect a server's tools with parameters, types, and descriptions.
+
+**`ogment --agentId <id> call <server> <tool> [args]`** — Call any tool. Returns clean JSON:
+```bash
+ogment --agentId work call salesforce query_accounts '{"limit":5}'
+ogment --agentId work call my-api get_customers '{"status":"active"}'
 ```
 
 **`ogment logout`** — Revoke token. All agent access stops immediately.
 
-## For Agent Developers
+## Agent Identity
 
-The CLI is designed for AI agents calling via shell exec. Every command supports `--json`. A typical agent workflow:
+Every `servers` and `call` command requires `--agentId`. This identifies which agent is making the request, and Ogment enforces per-agent permissions:
 
 ```bash
-ogment servers --json                                          # discover
-ogment servers salesforce --json                               # inspect tools
-ogment call salesforce query_accounts '{"status":"open"}'      # call
+# Agent "work" — sees only servers it's permitted for
+ogment --agentId work servers
+
+# Agent "work" — tool call is permission-checked and logged
+ogment --agentId work call salesforce query_accounts '{"limit":5}'
 ```
 
-Publish a skill on [ClawHub](https://clawhub.ai) that teaches the agent these three commands — and it has access to every integration on Ogment.
+Agents can also be identified via the `OGMENT_AGENT_ID` environment variable (set by OpenClaw per-agent skill config). The `--agentId` flag takes priority.
+
+**Server access types:**
+- **Public servers** — accessible to all agents (default)
+- **Restricted servers** — only agents with explicit permission can access
+
+Configure agent permissions in the Ogment dashboard under the **Agents** tab.
 
 ## Why Not Just Call APIs Directly?
 
 | | **Direct API + CLI** | **Through Ogment** |
 |---|---|---|
 | **Credentials** | API keys in env vars and config files. Every agent has a copy. | Credentials never leave Ogment. Agents get scoped, revocable tokens. |
-| **Permissions** | All-or-nothing. Agent has the key, agent can do anything. | Per-tool. Read-only, write with approval, or blocked. |
+| **Permissions** | All-or-nothing. Agent has the key, agent can do anything. | Per-agent, per-server. Public or restricted with full/read-only modes. |
 | **Human approval** | Not possible. | Built-in. Sensitive tools require human sign-off. |
 | **Team sharing** | Each person sets up their own keys. Onboarding = sharing secrets. | One workspace. Invite a teammate, same servers, same rules, no secrets shared. |
-| **Multi-agent** | Each AI client needs its own keys and config. Switch tools? Redo everything. | Define once. Every AI client connects to the same setup. |
+| **Multi-agent** | Each AI client needs its own keys and config. Switch tools? Redo everything. | Define once. Every agent connects to the same setup with its own permissions. |
 | **Workflows** | Rebuild skills, prompts, and tool chains for each AI client. | Author once as MCP servers, Skills, or Claude Plugins — works across every client. |
-| **Audit** | Hope you added logging. | Every call logged — user, agent, timestamp, args, result. |
+| **Audit** | Hope you added logging. | Every call logged — agent, user, server, tool, timestamp, args, result. |
 | **Revocation** | Rotate the API key, break everything that uses it. | Revoke one agent's token. Everything else keeps working. |
 
 **The CLI and MCP are the interface. Ogment is the infrastructure.**
@@ -104,7 +111,7 @@ Define your integrations, permissions, and workflows once — connect from any A
 
 | Client | How |
 |---|---|
-| **OpenClaw** | Agent calls `ogment` via `exec` tool |
+| **OpenClaw** | Agent calls `ogment` via `exec` tool with `--agentId` |
 | **Cursor** | MCP config with Ogment endpoint |
 | **Claude Desktop** | MCP config with Ogment endpoint |
 | **ChatGPT** | MCP config with Ogment endpoint |
@@ -117,6 +124,7 @@ Same servers, same tools, same permissions — regardless of which AI client you
 | Variable | Default | Description |
 |---|---|---|
 | `OGMENT_BASE_URL` | `https://dashboard.ogment.ai` | Ogment platform URL |
+| `OGMENT_AGENT_ID` | — | Agent identity (fallback for `--agentId` flag) |
 
 ## License
 

package/dist/api.d.ts

@@ -5,7 +5,9 @@ export interface OgmentServer {
     id: string;
     name: string;
     path: string;
+    description: string | null;
     enabled: boolean;
+    agentRestricted: boolean;
 }
 export interface OgmentOrg {
     orgId: string;

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB;AAMD,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,qBAY1C"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB;AAMD,wBAAsB,OAAO,CAAC,KAAK,EAAE,MAAM,qBAgB1C"}

package/dist/api.js

@@ -2,11 +2,16 @@
  * Ogment API client — calls the backend REST endpoints.
  */
 import { OGMENT_BASE_URL } from './config.js';
+import { getAgentId } from './mcp-client.js';
 // ---------------------------------------------------------------------------
 // /me — user identity + server list across all orgs
 // ---------------------------------------------------------------------------
 export async function fetchMe(token) {
-    const res = await fetch(`${OGMENT_BASE_URL}/api/v1/mcp-auth/me`, {
+    const url = new URL(`${OGMENT_BASE_URL}/api/v1/mcp-auth/me`);
+    const agentId = getAgentId();
+    if (agentId)
+        url.searchParams.set('agentId', agentId);
+    const res = await fetch(url.toString(), {
         headers: { Authorization: `Bearer ${token}` },
     });
     if (!res.ok) {

package/dist/cli.d.ts

@@ -2,10 +2,13 @@
 /**
  * Ogment CLI — Secure your AI agents' SaaS credentials.
  *
- *   ogment login <org/server>       Authenticate and configure servers
- *   ogment servers [path]           List servers / inspect tools
- *   ogment call <server> <tool>     Call a tool (returns JSON)
- *   ogment logout                   Revoke token and delete credentials
+ *   ogment login                         Authenticate with Ogment
+ *   ogment servers [path]                List servers / inspect tools
+ *   ogment call <server> <tool> [args]   Call a tool (returns JSON)
+ *   ogment logout                        Revoke token and delete credentials
+ *
+ * Global options:
+ *   --agent <id>   Identify as an agent (enforces per-agent permissions)
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;GAUG"}

package/dist/cli.js

@@ -2,10 +2,13 @@
 /**
  * Ogment CLI — Secure your AI agents' SaaS credentials.
  *
- *   ogment login <org/server>       Authenticate and configure servers
- *   ogment servers [path]           List servers / inspect tools
- *   ogment call <server> <tool>     Call a tool (returns JSON)
- *   ogment logout                   Revoke token and delete credentials
+ *   ogment login                         Authenticate with Ogment
+ *   ogment servers [path]                List servers / inspect tools
+ *   ogment call <server> <tool> [args]   Call a tool (returns JSON)
+ *   ogment logout                        Revoke token and delete credentials
+ *
+ * Global options:
+ *   --agent <id>   Identify as an agent (enforces per-agent permissions)
  */
 import { Command } from 'commander';
 import { callCommand } from './commands/call.js';
@@ -13,12 +16,20 @@ import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
 import { serversCommand } from './commands/servers.js';
 import { VERSION } from './config.js';
+import { setAgentId } from './mcp-client.js';
 import { BOLD, BRAND, DIM, SYM } from './ui.js';
 const program = new Command();
 program
     .name('ogment')
     .description('Ogment CLI — secure your AI agents\' SaaS credentials')
-    .version(VERSION);
+    .version(VERSION)
+    .option('--agentId <id>', 'Identify as an agent (enforces per-agent permissions)')
+    .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.agentId) {
+        setAgentId(opts.agentId);
+    }
+});
 // ── login ──────────────────────────────────────────────────────────────────
 program
     .command('login')
@@ -61,11 +72,15 @@ program.action(() => {
     console.log(`    ${BOLD('call')}      ${DIM('Call a tool on a server (returns JSON)')}`);
     console.log(`    ${BOLD('logout')}    ${DIM('Revoke token and delete credentials')}`);
     console.log();
+    console.log(`  ${BOLD('Global options:')}`);
+    console.log();
+    console.log(`    ${BOLD('--agentId <id>')}  ${DIM('Identify as an agent (per-agent permissions)')}`);
+    console.log();
     console.log(`  ${BOLD('Quick start:')}`);
     console.log();
     console.log(`    ${DIM('$')} ogment login`);
-    console.log(`    ${DIM('$')} ogment servers`);
-    console.log(`    ${DIM('$')} ogment call ${DIM('<server> <tool> [args-json]')}`);
+    console.log(`    ${DIM('$')} ogment --agentId work servers`);
+    console.log(`    ${DIM('$')} ogment --agentId work call ${DIM('<server> <tool> [args]')}`);
     console.log();
     console.log(`  ${SYM.lock} Your real API credentials ${BOLD('never leave Ogment')}.`);
     console.log(`     Agents get scoped, revocable tokens. Revoke anytime.`);

package/dist/commands/call.d.ts

@@ -2,8 +2,8 @@
  * `ogment call <server> <tool> [args]` — Invoke a tool on an Ogment server.
  *
  * Usage:
- *   ogment call ecommerce-api get__health
- *   ogment call ecommerce-api get__api_products_ '{"limit":2}'
+ *   ogment --agentId <id> call ecommerce-api get__health
+ *   ogment --agentId <id> call ecommerce-api get__api_products_ '{"limit":2}'
  *
  * Always outputs JSON (designed for agent consumption via exec).
  */

package/dist/commands/call.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../src/commands/call.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,iBAoC7B"}
+{"version":3,"file":"call.d.ts","sourceRoot":"","sources":["../../src/commands/call.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,iBA8C7B"}

package/dist/commands/call.js

@@ -2,23 +2,26 @@
  * `ogment call <server> <tool> [args]` — Invoke a tool on an Ogment server.
  *
  * Usage:
- *   ogment call ecommerce-api get__health
- *   ogment call ecommerce-api get__api_products_ '{"limit":2}'
+ *   ogment --agentId <id> call ecommerce-api get__health
+ *   ogment --agentId <id> call ecommerce-api get__api_products_ '{"limit":2}'
  *
  * Always outputs JSON (designed for agent consumption via exec).
  */
 import { requireCredentials } from '../auth.js';
 import { fetchMe } from '../api.js';
-import { callTool } from '../mcp-client.js';
+import { callTool, requireAgentId } from '../mcp-client.js';
 export async function callCommand(serverPath, toolName, argsJson) {
+    const agentId = requireAgentId();
     const creds = requireCredentials();
     const me = await fetchMe(creds.accessToken);
     // Find the server across all orgs
     const allServers = me.orgs.flatMap((org) => org.servers.map((s) => ({ ...s, orgSlug: org.orgSlug })));
     const server = allServers.find((s) => s.path === serverPath);
     if (!server) {
-        const available = allServers.map((s) => s.path).join(', ');
-        throw new Error(`Server "${serverPath}" not found. Available: ${available || 'none'}`);
+        const available = allServers.map((s) => s.path);
+        throw new Error(`Server "${serverPath}" not found.\n` +
+            `  Available servers: ${available.join(', ') || 'none'}\n` +
+            `  Run: ogment --agentId ${agentId} servers`);
     }
     let args = {};
     if (argsJson) {
@@ -26,9 +29,14 @@ export async function callCommand(serverPath, toolName, argsJson) {
             args = JSON.parse(argsJson);
         }
         catch {
-            throw new Error(`Invalid JSON arguments: ${argsJson}`);
+            throw new Error(`Invalid JSON arguments: ${argsJson}\n` +
+                `  Arguments must be a valid JSON string.\n` +
+                `  Example: ogment --agentId ${agentId} call ${serverPath} ${toolName} '{"key": "value"}'`);
         }
     }
     const result = await callTool(server.orgSlug, serverPath, creds.accessToken, toolName, args);
-    console.log(JSON.stringify(result, null, 2));
+    // Prefer structuredContent (parsed JSON), fall back to text content
+    const output = result.structuredContent
+        ?? JSON.parse(result.content?.[0]?.text ?? '{}');
+    console.log(JSON.stringify(output, null, 2));
 }

package/dist/commands/servers.d.ts

@@ -4,10 +4,10 @@
  * Fetches the live server list from /me (auto-refreshes on every call).
  *
  * Usage:
- *   ogment servers                     List all servers across all orgs
- *   ogment servers <path>              Show server details + tool list
- *   ogment servers --json              Machine-readable output
- *   ogment servers <path> --json       Machine-readable tool list
+ *   ogment --agentId <id> servers                List all servers
+ *   ogment --agentId <id> servers <path>         Show tools with parameters
+ *   ogment --agentId <id> servers --json         Machine-readable output
+ *   ogment --agentId <id> servers <path> --json  Machine-readable with schemas
  */
 export declare function serversCommand(serverPath: string | undefined, opts: {
     json?: boolean;

package/dist/commands/servers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"servers.d.ts","sourceRoot":"","sources":["../../src/commands/servers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,iBA6EzB"}
+{"version":3,"file":"servers.d.ts","sourceRoot":"","sources":["../../src/commands/servers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8CH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,iBA0FzB"}

package/dist/commands/servers.js

@@ -4,16 +4,42 @@
  * Fetches the live server list from /me (auto-refreshes on every call).
  *
  * Usage:
- *   ogment servers                     List all servers across all orgs
- *   ogment servers <path>              Show server details + tool list
- *   ogment servers --json              Machine-readable output
- *   ogment servers <path> --json       Machine-readable tool list
+ *   ogment --agentId <id> servers                List all servers
+ *   ogment --agentId <id> servers <path>         Show tools with parameters
+ *   ogment --agentId <id> servers --json         Machine-readable output
+ *   ogment --agentId <id> servers <path> --json  Machine-readable with schemas
  */
 import { requireCredentials } from '../auth.js';
 import { fetchMe } from '../api.js';
-import { fetchTools } from '../mcp-client.js';
-import { blank, BOLD, DIM, GREEN, heading, line, SYM } from '../ui.js';
+import { fetchTools, requireAgentId } from '../mcp-client.js';
+import { blank, BOLD, DIM, GREEN, heading, line, SYM, YELLOW } from '../ui.js';
+function formatType(prop) {
+    if (prop.enum)
+        return prop.enum.join(' | ');
+    if (prop.type === 'array' && prop.items?.type)
+        return `${prop.items.type}[]`;
+    return prop.type ?? 'unknown';
+}
+function renderParams(schema) {
+    const properties = (schema.properties ?? {});
+    const required = new Set((schema.required ?? []));
+    const entries = Object.entries(properties);
+    if (entries.length === 0) {
+        line(`      ${DIM('No parameters')}`, 0);
+        return;
+    }
+    for (const [name, prop] of entries) {
+        const req = required.has(name) ? YELLOW('required') : DIM('optional');
+        const type = DIM(`(${formatType(prop)})`);
+        const desc = prop.description ? ` — ${prop.description}` : '';
+        line(`      ${BOLD(name)} ${type} ${req}${desc}`, 0);
+    }
+}
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
 export async function serversCommand(serverPath, opts) {
+    const agentId = requireAgentId();
     const creds = requireCredentials();
     const me = await fetchMe(creds.accessToken);
     // Flatten all servers with their org slug
@@ -24,27 +50,30 @@ export async function serversCommand(serverPath, opts) {
             console.log(JSON.stringify(allServers, null, 2));
             return;
         }
-        heading('Your servers');
+        heading(`Servers for agent "${agentId}"`);
         if (allServers.length === 0) {
-            line(`${DIM('No servers found. Create one in the Ogment dashboard.')}`);
+            line(`No servers available for agent "${agentId}".`);
+            line(`${DIM('Grant access in the Ogment dashboard under the Agents tab.')}`);
             blank();
             return;
         }
         for (const server of allServers) {
-            const status = server.enabled ? GREEN('enabled') : DIM('disabled');
-            line(`${SYM.bullet}  ${BOLD(server.path.padEnd(24))} ${server.name.padEnd(24)} ${DIM(server.orgSlug.padEnd(16))} ${status}`);
+            const desc = server.description ? `\n      ${DIM(server.description)}` : '';
+            line(`${SYM.bullet}  ${BOLD(server.path.padEnd(24))} ${server.name}${desc}`);
         }
         blank();
-        line(`${DIM('Inspect a server:')} ${BOLD('ogment servers <path>')}`);
-        line(`${DIM('Call a tool:')}      ${BOLD('ogment call <server> <tool> [args]')}`);
+        line(`${DIM('Inspect tools:')} ogment --agentId ${agentId} servers <path>`);
+        line(`${DIM('Call a tool:')}    ogment --agentId ${agentId} call <server> <tool> [args]`);
         blank();
         return;
     }
     // ── Server detail + tools ──────────────────────────────────────────────
     const server = allServers.find((s) => s.path === serverPath);
     if (!server) {
-        const available = allServers.map((s) => s.path).join(', ');
-        throw new Error(`Server "${serverPath}" not found. Available: ${available || 'none'}`);
+        const available = allServers.map((s) => s.path);
+        throw new Error(`Server "${serverPath}" not found.\n` +
+            `  Available servers: ${available.join(', ') || 'none'}\n` +
+            `  Run: ogment --agentId ${agentId} servers`);
     }
     const tools = await fetchTools(server.orgSlug, serverPath, creds.accessToken);
     if (opts.json) {
@@ -54,19 +83,28 @@ export async function serversCommand(serverPath, opts) {
             enabled: server.enabled,
             orgSlug: server.orgSlug,
             toolCount: tools.length,
-            tools: tools.map((t) => ({ name: t.name, description: t.description })),
+            tools: tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
         }, null, 2));
         return;
     }
     heading(`${server.name} (${server.path})`);
-    line(`${BOLD('Org:')} ${server.orgSlug}`);
+    if (server.description) {
+        line(DIM(server.description));
+    }
     line(`${BOLD('Tools:')} ${tools.length}`);
     blank();
     for (const tool of tools) {
-        const desc = tool.description ? DIM(` — ${tool.description}`) : '';
-        line(`  ${GREEN(tool.name)}${desc}`);
+        const desc = tool.description
+            ? `\n      ${DIM(tool.description.split('\n')[0])}`
+            : '';
+        line(`  ${GREEN(tool.name)}${desc}`, 0);
+        renderParams(tool.inputSchema);
+        blank();
     }
-    blank();
-    line(`${DIM('Call a tool:')} ${BOLD(`ogment call ${serverPath} <tool> [args]`)}`);
+    line(`${DIM('Call a tool:')} ogment --agentId ${agentId} call ${serverPath} <tool> '{"param": "value"}'`);
     blank();
 }

package/dist/config.d.ts

@@ -19,5 +19,5 @@ export declare const CONFIG_DIR: string;
 export declare const CREDENTIALS_PATH: string;
 export declare const CLI_CLIENT_NAME = "Ogment CLI";
 export declare const CLI_REDIRECT_HOST = "127.0.0.1";
-export declare const VERSION = "0.2.3";
+export declare const VERSION = "0.2.4";
 //# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -33,4 +33,4 @@ export const CLI_REDIRECT_HOST = '127.0.0.1';
 // ---------------------------------------------------------------------------
 // Version
 // ---------------------------------------------------------------------------
-export const VERSION = '0.2.3';
+export const VERSION = '0.2.4';

package/dist/mcp-client.d.ts

@@ -19,6 +19,12 @@ interface McpToolCallResult {
     structuredContent?: unknown;
     isError?: boolean;
 }
+/** Set the agent ID for all subsequent MCP requests. */
+export declare function setAgentId(id: string | undefined): void;
+/** Get the current agent ID (flag > env var). */
+export declare function getAgentId(): string | undefined;
+/** Require an agent ID — throws if not set. */
+export declare function requireAgentId(): string;
 /** Fetch the list of tools available on a server. */
 export declare function fetchTools(orgSlug: string, serverPath: string, token: string): Promise<McpTool[]>;
 /** Call a tool on a server and return the result. */

package/dist/mcp-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,UAAU,iBAAiB;IACzB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAyHD,qDAAqD;AACrD,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,sBAKlF;AAED,qDAAqD;AACrD,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,8BAM9B"}
+{"version":3,"file":"mcp-client.d.ts","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,UAAU,iBAAiB;IACzB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAeD,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,QAEhD;AAED,iDAAiD;AACjD,wBAAgB,UAAU,uBAEzB;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,WAQ7B;AAuID,qDAAqD;AACrD,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,sBAKlF;AAED,qDAAqD;AACrD,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,8BAM9B"}

package/dist/mcp-client.js

@@ -12,14 +12,43 @@ import { MCP_ENDPOINT, VERSION } from './config.js';
 // ---------------------------------------------------------------------------
 /** Per-endpoint session cache (endpoint URL → session ID). */
 const sessions = new Map();
+/**
+ * Global agent ID — set via --agent flag or OGMENT_AGENT_ID env var.
+ * When set, the proxy enforces per-agent permissions.
+ */
+let _agentId;
+/** Set the agent ID for all subsequent MCP requests. */
+export function setAgentId(id) {
+    _agentId = id;
+}
+/** Get the current agent ID (flag > env var). */
+export function getAgentId() {
+    return _agentId ?? process.env.OGMENT_AGENT_ID;
+}
+/** Require an agent ID — throws if not set. */
+export function requireAgentId() {
+    const id = getAgentId();
+    if (!id) {
+        throw new Error('--agentId is required. Example: ogment --agentId <your-agent> servers');
+    }
+    return id;
+}
+/** Build common headers for MCP requests. */
+function baseHeaders(token) {
+    const h = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+    };
+    const agentId = getAgentId();
+    if (agentId)
+        h['x-ogment-agent-id'] = agentId;
+    return h;
+}
 /** Initialize an MCP session and return the session ID. */
 async function initializeSession(endpoint, token) {
     const res = await fetch(endpoint, {
         method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${token}`,
-        },
+        headers: baseHeaders(token),
         body: JSON.stringify({
             jsonrpc: '2.0',
             method: 'initialize',
@@ -33,14 +62,23 @@ async function initializeSession(endpoint, token) {
     });
     if (!res.ok) {
         const text = await res.text();
+        // Missing OAuth connections — user needs to connect the integration in the dashboard
+        if (text.includes('Missing required external MCP connections')) {
+            const match = text.match(/connections:\s*(.+?)"/);
+            const connections = match?.[1] ?? 'unknown';
+            throw new Error(`This server requires OAuth connections that are not set up: ${connections}\n` +
+                `  Go to the Ogment dashboard and connect the required integration.`);
+        }
+        // Agent permission denied — agent needs to be granted access
+        if (text.includes('AgentPermissionDenied') || text.includes('does not have access')) {
+            const agentId = getAgentId() ?? 'unknown';
+            throw new Error(`Agent "${agentId}" does not have access to this server.\n` +
+                `  Grant access in the Ogment dashboard under the Agents tab.`);
+        }
         const sanitized = text.length > 200 ? text.slice(0, 200) + '…' : text;
-        throw new Error(`MCP session init failed (${res.status}): ${sanitized}`);
-    }
-    const sessionId = res.headers.get('mcp-session-id');
-    if (!sessionId) {
-        throw new Error('MCP server did not return a session ID');
+        throw new Error(`MCP request failed (${res.status}): ${sanitized}`);
     }
-    return sessionId;
+    return res.headers.get('mcp-session-id');
 }
 /** Ensure a session exists for the given endpoint, initializing if needed. */
 async function ensureSession(endpoint, token) {
@@ -48,7 +86,8 @@ async function ensureSession(endpoint, token) {
     if (existing)
         return existing;
     const sessionId = await initializeSession(endpoint, token);
-    sessions.set(endpoint, sessionId);
+    if (sessionId)
+        sessions.set(endpoint, sessionId);
     return sessionId;
 }
 // ---------------------------------------------------------------------------
@@ -64,27 +103,26 @@ async function mcpRequest(orgSlug, serverPath, token, method, params) {
     };
     if (params)
         body.params = params;
+    const headers = baseHeaders(token);
+    if (sessionId)
+        headers['mcp-session-id'] = sessionId;
     let res = await fetch(endpoint, {
         method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${token}`,
-            'mcp-session-id': sessionId,
-        },
+        headers,
         body: JSON.stringify(body),
     });
     // Session expired — re-initialize once and retry
     if (res.status === 404 || res.status === 400) {
         sessions.delete(endpoint);
         const newSessionId = await initializeSession(endpoint, token);
-        sessions.set(endpoint, newSessionId);
+        if (newSessionId)
+            sessions.set(endpoint, newSessionId);
+        const retryHeaders = baseHeaders(token);
+        if (newSessionId)
+            retryHeaders['mcp-session-id'] = newSessionId;
         res = await fetch(endpoint, {
             method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${token}`,
-                'mcp-session-id': newSessionId,
-            },
+            headers: retryHeaders,
             body: JSON.stringify(body),
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ogment",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Ogment Vault CLI — secure your AI agents' SaaS credentials",
   "type": "module",
   "bin": {
@@ -48,6 +48,7 @@
   "dependencies": {
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
+    "ogment": "^0.2.3",
     "open": "^10.2.0",
     "ora": "^8.2.0"
   },