@withone/mcp 1.3.0 → 1.4.0

package/build/client.js

@@ -9,6 +9,62 @@
 import axios from 'axios';
 import FormData from 'form-data';
 import { fetchPaginatedData, replacePathVariables } from './helpers.js';
+/** Header names that only the server may set on an outgoing request. */
+const RESERVED_HEADER_PREFIX = 'x-one-';
+/**
+ * Drops any caller-supplied header that One itself controls (`x-one-secret`,
+ * `x-one-connection-key`, `x-one-action-id`, ...). Comparison is
+ * case-insensitive because HTTP header names are.
+ */
+export function stripReservedHeaders(headers) {
+    if (!headers)
+        return {};
+    return Object.fromEntries(Object.entries(headers)
+        .filter(([name]) => !name.toLowerCase().startsWith(RESERVED_HEADER_PREFIX))
+        .map(([name, value]) => [name, String(value)]));
+}
+/**
+ * Bounds an upstream error body before it is logged: small payloads pass
+ * through, larger ones are truncated to a string, and an unserializable value
+ * is replaced with a placeholder. Keeps a huge or odd error response from
+ * bloating a single log line.
+ */
+function summarizeErrorData(data) {
+    if (data === undefined || data === null)
+        return undefined;
+    let serialized;
+    try {
+        serialized = typeof data === 'string' ? data : JSON.stringify(data);
+    }
+    catch {
+        return '[unserializable response body]';
+    }
+    const MAX = 1000;
+    return serialized.length <= MAX ? data : `${serialized.slice(0, MAX)}… (${serialized.length} chars, truncated)`;
+}
+/**
+ * A log-safe summary of a failed request. Axios errors carry the full request
+ * config, including the `x-one-secret` header, so they must never be logged
+ * whole. Only the status, the upstream message, the route (query stripped), and
+ * a bounded copy of the response body are kept.
+ */
+export function describeError(error) {
+    if (axios.isAxiosError(error)) {
+        const url = error.config?.url;
+        return {
+            status: error.response?.status,
+            statusText: error.response?.statusText,
+            method: error.config?.method?.toUpperCase(),
+            url: typeof url === 'string' ? url.split('?')[0] : undefined,
+            message: error.message,
+            data: summarizeErrorData(error.response?.data),
+        };
+    }
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message };
+    }
+    return { error: String(error) };
+}
 /**
  * Client for interacting with the One API
  */
@@ -18,6 +74,7 @@ export class OneClient {
     identity;
     identityType;
     connectionKeys;
+    fetchConnectors = true;
     connections = [];
     connectors = [];
     isInitialized = false;
@@ -46,6 +103,7 @@ export class OneClient {
             this.identity = optionsOrSecret.identity;
             this.identityType = optionsOrSecret.identityType;
             this.connectionKeys = optionsOrSecret.connectionKeys;
+            this.fetchConnectors = optionsOrSecret.fetchConnectors ?? true;
         }
     }
     /**
@@ -58,15 +116,15 @@ export class OneClient {
         }
         const results = await Promise.allSettled([
             this.fetchConnections(),
-            this.fetchConnectionDefinitions(),
+            this.fetchConnectors ? this.fetchConnectionDefinitions() : Promise.resolve(),
         ]);
         const [connectionsResult, connectorsResult] = results;
         if (connectionsResult.status === 'rejected') {
-            console.error("Failed to fetch connections:", connectionsResult.reason);
+            console.error("Failed to fetch connections:", describeError(connectionsResult.reason));
             this.connections = [];
         }
         if (connectorsResult.status === 'rejected') {
-            console.error("Failed to fetch connectors:", connectorsResult.reason);
+            console.error("Failed to fetch connectors:", describeError(connectorsResult.reason));
             this.connectors = [];
         }
         this.isInitialized = true;
@@ -105,7 +163,7 @@ export class OneClient {
             this.connections = await fetchPaginatedData(url, headers, Object.keys(additionalParams).length > 0 ? additionalParams : undefined);
         }
         catch (error) {
-            console.error("Failed to fetch connections:", error);
+            console.error("Failed to fetch connections:", describeError(error));
             this.connections = [];
             throw error;
         }
@@ -120,7 +178,7 @@ export class OneClient {
             this.connectors = await fetchPaginatedData(url, headers);
         }
         catch (error) {
-            console.error("Failed to fetch connection definitions:", error);
+            console.error("Failed to fetch connection definitions:", describeError(error));
             this.connectors = [];
             throw error;
         }
@@ -162,7 +220,7 @@ export class OneClient {
             return response.data || [];
         }
         catch (error) {
-            console.error("Error searching available actions:", error);
+            console.error("Error searching available actions:", describeError(error));
             if (axios.isAxiosError(error)) {
                 throw new Error(`Failed to search available actions: ${error.response?.status} ${error.response?.statusText}`);
             }
@@ -204,7 +262,7 @@ export class OneClient {
             return actions[0];
         }
         catch (error) {
-            console.error("Error fetching action details:", error);
+            console.error("Error fetching action details:", describeError(error));
             if (axios.isAxiosError(error)) {
                 throw new Error(`Failed to fetch action details: ${error.response?.status} ${error.response?.statusText}`);
             }
@@ -232,7 +290,7 @@ export class OneClient {
             };
         }
         catch (error) {
-            console.error("Error fetching action knowledge:", error);
+            console.error("Error fetching action knowledge:", describeError(error));
             throw error;
         }
     }
@@ -267,7 +325,7 @@ export class OneClient {
                 };
             }
             catch (error) {
-                console.error(`Failed to resolve allowed action ${actionId}:`, error);
+                console.error(`Failed to resolve allowed action ${actionId}:`, describeError(error));
                 return null;
             }
         }));
@@ -286,16 +344,25 @@ export class OneClient {
         const action = preloadedAction ?? await this.getActionDetails(actionId);
         const method = action.method;
         const contentType = isFormData ? 'multipart/form-data' : isFormUrlEncoded ? 'application/x-www-form-urlencoded' : 'application/json';
+        // Caller-supplied headers are merged first and may adjust things like
+        // Content-Type, but they can never override One's own routing and auth
+        // headers. Those are applied last, after the connection and action
+        // allowlist checks in index.ts have already passed, so an `x-one-*`
+        // header in `headers` cannot redirect the call to another connection,
+        // action, or secret.
+        // Drop One's default Content-Type (any casing) so the caller's choice,
+        // merged in below, is not clobbered when the auth headers are applied last.
+        const authHeaders = Object.fromEntries(Object.entries(this.generateHeaders()).filter(([name]) => name.toLowerCase() !== 'content-type'));
         const requestHeaders = {
-            ...this.generateHeaders(),
+            'Content-Type': contentType,
+            ...stripReservedHeaders(headers),
+            ...authHeaders,
             'x-one-connection-key': connectionKey,
             'x-one-action-id': action._id,
-            'Content-Type': contentType,
-            ...headers
         };
-        const finalActionPath = pathVariables
-            ? replacePathVariables(action.path, pathVariables)
-            : action.path;
+        // Always substitute: a template sent with its {{placeholders}} unfilled
+        // only fails upstream, while this names the variables the path expects.
+        const finalActionPath = replacePathVariables(action.path, pathVariables ?? {});
         const normalizedPath = finalActionPath.startsWith('/') ? finalActionPath : `/${finalActionPath}`;
         const url = `${this.baseUrl}/v1/passthrough${normalizedPath}`;
         let requestData = data;
@@ -368,7 +435,7 @@ export class OneClient {
             };
         }
         catch (error) {
-            console.error("Error executing passthrough request:", error);
+            console.error("Error executing passthrough request:", describeError(error));
             if (axios.isAxiosError(error)) {
                 throw new Error(`Failed to execute passthrough request: ${error.response?.status} ${error.response?.statusText}`);
             }
@@ -408,7 +475,7 @@ export class OneClient {
     async refresh() {
         await Promise.allSettled([
             this.fetchConnections(),
-            this.fetchConnectionDefinitions(),
+            this.fetchConnectors ? this.fetchConnectionDefinitions() : Promise.resolve(),
         ]);
     }
 }

package/build/client.test.js

@@ -0,0 +1,109 @@
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { OneClient, stripReservedHeaders, describeError } from './client.js';
+// A passthrough call must never let the caller override One's own routing/auth
+// headers (the scoping bypass), and a failed call must never log the secret.
+const SECRET = 'sk_test_REALSECRET_abc123';
+const ACTION = { _id: 'conn_mod_def::ALLOWED_ACTION', method: 'GET', path: '/v1/things', tags: [] };
+const exec = (extra) => ({
+    platform: 'test',
+    actionId: 'conn_mod_def::ALLOWED_ACTION',
+    connectionKey: 'live::allowed::default::aaaa',
+    ...extra,
+});
+describe("executePassthroughRequest keeps One's headers authoritative", () => {
+    let server;
+    let base = '';
+    let received = [];
+    let failBody = null;
+    before(async () => {
+        server = http.createServer((req, res) => {
+            received.push({ headers: req.headers });
+            if (failBody !== null) {
+                res.writeHead(422, { 'Content-Type': 'application/json' });
+                res.end(failBody);
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: true }));
+        });
+        await new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+        base = `http://127.0.0.1:${server.address().port}`;
+    });
+    after(() => {
+        server.close();
+    });
+    beforeEach(() => {
+        received = [];
+        failBody = null;
+    });
+    it('a caller cannot override the x-one-* routing/auth headers', async () => {
+        const client = new OneClient(SECRET, base);
+        await client.executePassthroughRequest(exec({
+            headers: {
+                'x-one-connection-key': 'live::EXCLUDED::default::zzzz',
+                'X-One-Secret': 'sk_live_stolen',
+                'X-ONE-ACTION-ID': 'conn_mod_def::OTHER',
+                'x-custom-trace': 't-1',
+            },
+        }), ACTION);
+        const h = received[0].headers;
+        assert.equal(h['x-one-connection-key'], 'live::allowed::default::aaaa');
+        assert.equal(h['x-one-secret'], SECRET);
+        assert.equal(h['x-one-action-id'], 'conn_mod_def::ALLOWED_ACTION');
+        assert.equal(h['x-custom-trace'], 't-1', 'a non-reserved custom header still passes through');
+        assert.equal(h['content-type'], 'application/json', 'the default content type is kept');
+    });
+    it('names the expected path variables instead of sending an unfilled template', async () => {
+        const client = new OneClient(SECRET, base);
+        const templated = { ...ACTION, path: '/v1/things/{{thingId}}' };
+        await assert.rejects(client.executePassthroughRequest(exec({}), templated), /pass pathVariables with: thingId/);
+        assert.equal(received.length, 0, 'nothing is sent upstream');
+        await client.executePassthroughRequest(exec({ pathVariables: { thing_id: 7 } }), templated);
+        assert.equal(received.length, 1);
+    });
+    it('a caller may still set Content-Type, in any casing', async () => {
+        const client = new OneClient(SECRET, base);
+        await client.executePassthroughRequest(exec({ headers: { 'content-type': 'text/plain' } }), ACTION);
+        assert.equal(received[0].headers['content-type'], 'text/plain');
+    });
+    it('a failed call throws with the status, never logs the secret, and bounds the body', async () => {
+        failBody = JSON.stringify({ error: 'upstream said no', padding: 'x'.repeat(2000) });
+        const client = new OneClient(SECRET, base);
+        const logged = [];
+        const original = console.error;
+        console.error = (...args) => {
+            logged.push(args.map((a) => (typeof a === 'string' ? a : JSON.stringify(a))).join(' '));
+        };
+        let message = '';
+        try {
+            await client.executePassthroughRequest(exec({}), ACTION);
+        }
+        catch (error) {
+            message = error.message;
+        }
+        finally {
+            console.error = original;
+        }
+        const log = logged.join('\n');
+        assert.ok(!log.includes(SECRET), 'the secret never reaches the log');
+        assert.ok(log.includes('422') && log.includes('upstream said no'), 'the log still says what failed');
+        assert.ok(log.includes('truncated'), 'a huge upstream body is bounded');
+        assert.ok(message.includes('422'), 'the thrown tool error carries the status');
+    });
+});
+describe('stripReservedHeaders', () => {
+    it('drops x-one-* case-insensitively and stringifies values', () => {
+        assert.deepEqual(stripReservedHeaders({ 'X-One-Secret': 'a', 'x-one-action-id': 'b', Accept: 'x' }), { Accept: 'x' });
+        assert.deepEqual(stripReservedHeaders({ n: 5 }), { n: '5' });
+        assert.deepEqual(stripReservedHeaders(undefined), {});
+    });
+});
+describe('describeError', () => {
+    it('summarizes a plain error to its name and message', () => {
+        const described = describeError(new Error('boom'));
+        assert.equal(described.name, 'Error');
+        assert.equal(described.message, 'boom');
+    });
+});

package/build/helpers.js

@@ -69,8 +69,7 @@ export async function fetchPaginatedData(baseUrl, headers, additionalParams) {
  * in full, plus a trailer and a `sections` list naming what was omitted); a
  * small doc is returned whole. `section` selects named section(s), `toc`
  * returns the full table of contents, and `full` (or `section: "all"`) returns
- * the document verbatim. Only the digest and full cases carry the API request
- * guidance, so `wrap` is set for those.
+ * the document verbatim.
  *
  * @param knowledge - The raw knowledge markdown for the action
  * @param method - The action's HTTP method (echoed into the envelope)
@@ -104,7 +103,6 @@ export function buildKnowledgeResponse(knowledge, method, platform, actionId, op
                 ? `Section "${picked.query}" matches several sections; pick one by id or full heading.`
                 : `No section named "${picked.query}". Use one of the names below, or full: true.`;
             return {
-                wrap: false,
                 text: `${lead}\n\n${listing}`,
                 structured: {
                     error: lead,
@@ -116,7 +114,6 @@ export function buildKnowledgeResponse(knowledge, method, platform, actionId, op
             };
         }
         return {
-            wrap: false,
             text: picked.markdown,
             structured: {
                 title: doc.title,
@@ -133,7 +130,6 @@ export function buildKnowledgeResponse(knowledge, method, platform, actionId, op
             ? fullToc.map((t) => `${'  '.repeat(Math.max(0, t.level - 1))}${t.heading} [${t.id}] (${t.chars} chars)`).join('\n')
             : '(this document has no sections)';
         return {
-            wrap: false,
             text: `Table of contents. Load any by name with section: "<id or heading>", or the whole document with full: true.\n\n${listing}`,
             structured: { title: doc.title, method, chars: doc.chars, sections: fullToc },
         };
@@ -141,18 +137,17 @@ export function buildKnowledgeResponse(knowledge, method, platform, actionId, op
     // `full`, and any document small enough to keep whole, are returned verbatim
     // rather than reconstructed from the parsed tree, so nothing is reformatted.
     if (wantFull) {
-        return { wrap: true, text: knowledge, structured: { title: doc.title, method, truncated: false } };
+        return { text: knowledge, structured: { title: doc.title, method, truncated: false } };
     }
     const digest = buildDigest(doc);
     if (!digest.truncated) {
-        return { wrap: true, text: knowledge, structured: { title: doc.title, method, truncated: false } };
+        return { text: knowledge, structured: { title: doc.title, method, truncated: false } };
     }
     const toc = omittedSections(digest);
     const text = [renderDigestBanner(digest), digest.markdown, renderDigestNotice(digest, platform, actionId)]
         .filter(Boolean)
         .join('\n\n');
     return {
-        wrap: true,
         text,
         structured: {
             title: doc.title,
@@ -165,42 +160,6 @@ export function buildKnowledgeResponse(knowledge, method, platform, actionId, op
         },
     };
 }
-/**
- * Builds action knowledge with API request structure guidance.
- * @param knowledge - The raw knowledge content for the action
- * @param method - The HTTP method for the action
- * @param baseUrl - The base URL for One API
- * @param platform - The platform name (used for connection key)
- * @param actionId - The action ID
- * @returns Complete formatted knowledge with API guidance
- */
-export function buildActionKnowledgeWithGuidance(knowledge, method, baseUrl, platform, actionId) {
-    const cleanBaseUrl = baseUrl.replace(/\/$/, '');
-    return `${knowledge}
-
-API REQUEST STRUCTURE
-======================
-URL: ${cleanBaseUrl}/v1/passthrough/{{PATH}}
-
-IMPORTANT: When constructing the URL, only include the API endpoint path after the base URL.
-Do NOT include the full third-party API URL.
-
-Examples:
-✅ Correct: ${cleanBaseUrl}/v1/passthrough/crm/v3/objects/contacts/search
-❌ Incorrect: ${cleanBaseUrl}/v1/passthrough/https://api.hubapi.com/crm/v3/objects/contacts/search
-
-METHOD: ${method}
-
-HEADERS:
-- x-one-secret: {{process.env.ONE_SECRET}}
-- x-one-connection-key: {{process.env.ONE_${platform.toUpperCase()}_CONNECTION_KEY}}
-- x-one-action-id: ${actionId}
-- ... (other headers)
-
-BODY: {{BODY}}
-
-QUERY PARAMS: {{QUERY_PARAMS}}`;
-}
 /**
  * Uppercases a platform id into an env-var segment, collapsing every
  * non-alphanumeric run to a single underscore ("ship-station" -> "SHIP_STATION").
@@ -301,37 +260,38 @@ const response = await fetch("${apiBase}/v1/passthrough${path}", {
 });
 \`\`\``;
 }
+/** Folds a path variable name for loose matching: `ticket_id`, `ticketId`, `TICKET-ID` all fold to `ticketid`. */
+const foldVariableName = (name) => name.toLowerCase().replace(/[\s_-]/g, '');
 /**
  * Replaces path variables in a template string with actual values.
- * Path variables can be in either format: {variableName} or {{variableName}} and will be replaced with corresponding values.
+ * Path variables can be in either format: {variableName} or {{variableName}}.
+ * A variable is looked up by its exact name first, then by name ignoring case,
+ * underscores, hyphens and spaces, because knowledge docs and path templates
+ * do not always spell a variable the same way (`ticket_id` vs `{{ticketId}}`).
  * @param path - The template string containing path variables in {variableName} or {{variableName}} format
  * @param variables - Object containing variable names as keys and their replacement values
  * @returns The path string with all variables replaced by their encoded values
- * @throws Error if any required variable is missing, null, undefined, or empty string
+ * @throws Error if any required variable is missing, null, undefined, or empty string, naming every variable the path expects
  */
 export function replacePathVariables(path, variables) {
     if (!path)
         return path;
-    let result = path;
-    // First, replace double bracket variables {{variableName}}
-    result = result.replace(/\{\{([^}]+)\}\}/g, (match, variable) => {
-        const trimmedVariable = variable.trim();
-        const value = variables[trimmedVariable];
-        if (value === undefined || value === null || value === '') {
-            throw new Error(`Missing value for path variable: ${trimmedVariable}`);
-        }
-        return encodeURIComponent(value.toString());
-    });
-    // Then, replace single bracket variables {variableName}
-    result = result.replace(/\{([^}]+)\}/g, (match, variable) => {
-        const trimmedVariable = variable.trim();
-        const value = variables[trimmedVariable];
+    const expected = [...path.matchAll(/\{\{([^}]+)\}\}|\{([^{}]+)\}/g)].map((m) => (m[1] ?? m[2]).trim());
+    const folded = new Map();
+    for (const [key, value] of Object.entries(variables ?? {})) {
+        if (!folded.has(foldVariableName(key)))
+            folded.set(foldVariableName(key), value);
+    }
+    const lookup = (variable) => {
+        const name = variable.trim();
+        const value = name in (variables ?? {}) ? variables[name] : folded.get(foldVariableName(name));
         if (value === undefined || value === null || value === '') {
-            throw new Error(`Missing value for path variable: ${trimmedVariable}`);
+            throw new Error(`Missing value for path variable: ${name}. This action's path is ${path}; pass pathVariables with: ${[...new Set(expected)].join(', ')}.`);
         }
         return encodeURIComponent(value.toString());
-    });
-    return result;
+    };
+    // Double brackets first, so {{name}} is not read as {name} wrapped in braces.
+    return path.replace(/\{\{([^}]+)\}\}/g, (_match, variable) => lookup(variable)).replace(/\{([^}]+)\}/g, (_match, variable) => lookup(variable));
 }
 const PERMISSION_METHODS = {
     read: ["GET"],
@@ -375,3 +335,45 @@ export function computeConnectionAccess(platform, permissions, allowedActionIds,
     }
     return { policy: "full" };
 }
+/**
+ * Builds the `list_one_integrations` response: the user's active connections,
+ * each with the access the current config confers. Access is only defined per
+ * connection, so unconnected platforms are left out unless `available` is
+ * passed (knowledge/code-gen mode, where an agent may write code against a
+ * platform the user has not connected yet and needs its kebab-case name).
+ * @param connections - The user's connections
+ * @param access - The access config: permission level, action allowlist, and
+ *   the allowlist already resolved to action metadata
+ * @param available - Connection definitions to list as available platforms
+ */
+export function buildIntegrationsResponse(connections, access, available) {
+    const active = connections.filter((conn) => conn.active);
+    const response = {
+        connections: active.map((conn) => ({
+            platform: conn.platform,
+            key: conn.key,
+            tags: conn.tags ?? [],
+            access: computeConnectionAccess(conn.platform, access.permissions, access.actionIds, access.resolvedAllowed),
+        })),
+        summary: { connectedCount: active.length },
+    };
+    if (available) {
+        const platforms = available.filter((def) => def.active && !def.deprecated);
+        response.availablePlatforms = platforms.map((def) => ({
+            platform: def.platform,
+            name: def.name,
+            category: def.category,
+        }));
+        response.summary.availableCount = platforms.length;
+    }
+    return response;
+}
+/** Back office tag for actions agents must not use (a `custom` action covers them). */
+export const HIDDEN_FROM_AGENTS_TAG = "hidden:agents";
+/**
+ * Whether an action is hidden from executing agents. Knowledge/code-gen mode
+ * still sees these: writing integration code may target the raw endpoint.
+ */
+export function isHiddenFromAgents(tags) {
+    return (tags ?? []).includes(HIDDEN_FROM_AGENTS_TAG);
+}

package/build/hidden-actions.test.js

@@ -0,0 +1,12 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { isHiddenFromAgents } from './helpers.js';
+describe('isHiddenFromAgents', () => {
+    it('flags only actions tagged hidden:agents', () => {
+        assert.equal(isHiddenFromAgents(['hidden:agents']), true);
+        assert.equal(isHiddenFromAgents(['custom', 'hidden:agents']), true);
+        assert.equal(isHiddenFromAgents(['custom']), false);
+        assert.equal(isHiddenFromAgents([]), false);
+        assert.equal(isHiddenFromAgents(undefined), false);
+    });
+});

package/build/index.js

@@ -11,7 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { OneClient } from './client.js';
-import { buildActionKnowledgeWithGuidance, buildKnowledgeModeGuidance, buildKnowledgeResponse, filterByPermissions, isMethodAllowed, isActionAllowed, computeConnectionAccess, } from './helpers.js';
+import { buildKnowledgeModeGuidance, buildKnowledgeResponse, filterByPermissions, isMethodAllowed, isActionAllowed, buildIntegrationsResponse, isHiddenFromAgents, } from './helpers.js';
 import { listOneIntegrationsToolConfig, searchOnePlatformActionsToolConfig, getOneActionKnowledgeToolConfig, executeOneActionToolConfig } from './schemas.js';
 const SERVER_NAME = "one-mcp-server";
 const SERVER_VERSION = "1.0.0";
@@ -41,6 +41,8 @@ const oneClient = new OneClient({
     identity: ONE_IDENTITY,
     identityType: ONE_IDENTITY_TYPE,
     connectionKeys: ONE_CONNECTION_KEYS,
+    // The platform catalog is only listed in knowledge/code-gen mode.
+    fetchConnectors: ONE_KNOWLEDGE_AGENT,
 });
 let oneInitialized = false;
 let initializationPromise = null;
@@ -88,37 +90,18 @@ if (!ONE_KNOWLEDGE_AGENT) {
 }
 async function handleGetIntegrations(args) {
     try {
-        const connectedIntegrations = oneClient.getUserConnections();
-        const availableIntegrations = oneClient.getAvailableConnectors();
-        const activeConnections = connectedIntegrations.filter(conn => conn.active);
-        let activePlatforms = availableIntegrations.filter(def => def.active && !def.deprecated);
-        // When connection keys are scoped, only show platforms that match active connections
-        if (!ONE_CONNECTION_KEYS.includes("*")) {
-            const connectedPlatforms = new Set(activeConnections.map(conn => conn.platform));
-            activePlatforms = activePlatforms.filter(def => connectedPlatforms.has(def.platform));
-        }
         // Resolve the action allowlist to per-platform metadata (method-filtered by
         // the permission level) once, so each connection can report the exact
         // actions it may run. Only needed when an action allowlist is set.
         const resolvedAllowed = (await oneClient.resolveAllowedActions(ONE_ACTION_IDS))
             .filter(action => isMethodAllowed(action.method, ONE_PERMISSIONS));
-        const structuredResponse = {
-            connections: activeConnections.map(conn => ({
-                platform: conn.platform,
-                key: conn.key,
-                tags: conn.tags ?? [],
-                access: computeConnectionAccess(conn.platform, ONE_PERMISSIONS, ONE_ACTION_IDS, resolvedAllowed)
-            })),
-            availablePlatforms: activePlatforms.map(def => ({
-                platform: def.platform,
-                name: def.name,
-                category: def.category
-            })),
-            summary: {
-                connectedCount: activeConnections.length,
-                availableCount: activePlatforms.length
-            }
-        };
+        // Execute mode lists only connections: every connection carries its
+        // access, and the full catalog (800+ platforms) would sit in the agent's
+        // context for the rest of the session. Knowledge/code-gen mode also lists
+        // available platforms so code can target one that is not connected yet,
+        // unless connection keys are scoped.
+        const includeAvailable = ONE_KNOWLEDGE_AGENT && ONE_CONNECTION_KEYS.includes("*");
+        const structuredResponse = buildIntegrationsResponse(oneClient.getUserConnections(), { permissions: ONE_PERMISSIONS, actionIds: ONE_ACTION_IDS, resolvedAllowed }, includeAvailable ? oneClient.getAvailableConnectors() : undefined);
         return {
             content: [
                 {
@@ -136,7 +119,9 @@ async function handleGetIntegrations(args) {
 async function handleSearchPlatformActions(args) {
     try {
         // Force knowledge mode when ONE_KNOWLEDGE_AGENT is enabled
-        const agentType = ONE_KNOWLEDGE_AGENT ? "knowledge" : args.agentType;
+        // With execute available, default to the execute catalog: it hides actions
+        // tagged hidden:agents and offers the custom actions that replace them.
+        const agentType = ONE_KNOWLEDGE_AGENT ? "knowledge" : (args.agentType ?? "execute");
         let actions = await oneClient.searchAvailableActions(args.platform, args.query, agentType);
         // Apply permission-level filtering
         actions = filterByPermissions(actions, ONE_PERMISSIONS);
@@ -228,20 +213,23 @@ async function handleGetActionKnowledge(args) {
                 ],
             };
         }
+        if (isHiddenFromAgents((await oneClient.getActionDetails(actionId)).tags)) {
+            throw new McpError(ErrorCode.InvalidRequest, `Action "${actionId}" is hidden from agents; search for the task again to find the action to use instead`);
+        }
         const { knowledge, method } = await oneClient.getActionKnowledge(actionId);
         const response = buildKnowledgeResponse(knowledge, method, args.platform, actionId, {
             section: args.section,
             full: args.full,
             toc: args.toc,
         });
-        const text = response.wrap
-            ? buildActionKnowledgeWithGuidance(response.text, method, oneClient.getBaseUrl(), args.platform, actionId)
-            : response.text;
+        // Execute mode returns the documentation alone: execute_one_action builds
+        // the passthrough request itself, so the raw-HTTP guidance code-gen mode
+        // appends (base URL, x-one-* headers, env var names) would only add tokens.
         return {
             content: [
                 {
                     type: "text",
-                    text,
+                    text: response.text,
                 },
             ],
             structuredContent: response.structured,
@@ -263,6 +251,9 @@ async function handleExecuteOneAction(args) {
             }
         }
         const actionDetails = await oneClient.getActionDetails(args.actionId);
+        if (isHiddenFromAgents(actionDetails.tags)) {
+            throw new McpError(ErrorCode.InvalidRequest, `Action "${args.actionId}" is hidden from agents; search for the task again to find the action to use instead`);
+        }
         if (!isMethodAllowed(actionDetails.method, ONE_PERMISSIONS)) {
             throw new McpError(ErrorCode.InvalidRequest, `Method "${actionDetails.method}" is not allowed under "${ONE_PERMISSIONS}" permission level`);
         }

package/build/integrations-response.test.js

@@ -0,0 +1,40 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildIntegrationsResponse } from './helpers.js';
+const conn = (platform, active = true) => ({ key: `live::${platform}::default::k`, platform, tags: [], active });
+const def = (platform, extra = {}) => ({ platform, name: platform.toUpperCase(), category: 'Test', active: true, deprecated: false, ...extra });
+const FULL = { permissions: 'admin', actionIds: ['*'], resolvedAllowed: [] };
+describe('buildIntegrationsResponse', () => {
+    it('lists only active connections, without the platform catalog', () => {
+        const r = buildIntegrationsResponse([conn('gmail'), conn('slack', false)], FULL);
+        assert.deepEqual(r.connections.map((c) => c.platform), ['gmail']);
+        assert.equal(r.availablePlatforms, undefined);
+        assert.deepEqual(r.summary, { connectedCount: 1 });
+    });
+    it('keeps the per-connection access', () => {
+        const r = buildIntegrationsResponse([conn('gmail')], { permissions: 'read', actionIds: ['*'], resolvedAllowed: [] });
+        assert.deepEqual(r.connections[0].access, { policy: 'methods', methods: ['GET'] });
+        const scoped = buildIntegrationsResponse([conn('gmail')], {
+            permissions: 'admin',
+            actionIds: ['act_1'],
+            resolvedAllowed: [{ actionId: 'act_1', title: 'Send Email', method: 'POST', platform: 'gmail' }],
+        });
+        assert.deepEqual(scoped.connections[0].access, {
+            policy: 'actions',
+            actions: [{ actionId: 'act_1', title: 'Send Email', method: 'POST' }],
+        });
+    });
+    it('adds active, non-deprecated platforms when a catalog is passed (code-gen mode)', () => {
+        const r = buildIntegrationsResponse([conn('gmail')], FULL, [
+            def('gmail'),
+            def('hubspot'),
+            def('old-crm', { deprecated: true }),
+            def('beta-thing', { active: false }),
+        ]);
+        assert.deepEqual(r.availablePlatforms, [
+            { platform: 'gmail', name: 'GMAIL', category: 'Test' },
+            { platform: 'hubspot', name: 'HUBSPOT', category: 'Test' },
+        ]);
+        assert.deepEqual(r.summary, { connectedCount: 1, availableCount: 2 });
+    });
+});

package/build/knowledge-response.test.js

@@ -18,7 +18,6 @@ const SMALL = '# Tiny\n\n## Method\nGET\n\n## URL\n/x';
 describe('buildKnowledgeResponse', () => {
     it('digests a large doc: request-building sections in full, omitted ones named in the envelope', () => {
         const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', {});
-        assert.equal(r.wrap, true);
         assert.equal(r.structured.truncated, true);
         assert.ok(r.structured.omitted >= 1);
         assert.ok(Array.isArray(r.structured.sections) && r.structured.sections.length >= 1);
@@ -31,20 +30,17 @@ describe('buildKnowledgeResponse', () => {
     });
     it('returns the whole table of contents for toc, with no bodies', () => {
         const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { toc: true });
-        assert.equal(r.wrap, false);
         assert.ok(r.structured.sections.length >= 5);
         assert.ok(r.text.includes('[response-fields]'));
         assert.ok(!r.text.includes('Response Fields field 100'));
     });
     it('returns a named section with its body and what it resolved to', () => {
         const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { section: 'Response Fields' });
-        assert.equal(r.wrap, false);
         assert.deepEqual(r.structured.resolved.map((s) => s.heading), ['Response Fields']);
         assert.ok(r.text.includes('Response Fields field 100'));
     });
     it('reports a not-found section with a bounded candidate list', () => {
         const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { section: 'nope' });
-        assert.equal(r.wrap, false);
         assert.ok(r.structured.error);
         assert.equal(r.structured.reason, 'not-found');
         assert.ok(r.structured.sections.length >= 1);
@@ -53,21 +49,26 @@ describe('buildKnowledgeResponse', () => {
     it('treats section: "all" and full: true as the verbatim whole document', () => {
         for (const opts of [{ section: 'all' }, { full: true }]) {
             const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', opts);
-            assert.equal(r.wrap, true);
             assert.equal(r.text, LARGE);
             assert.equal(r.structured.truncated, false);
         }
     });
     it('returns a small doc verbatim with no digest', () => {
         const r = buildKnowledgeResponse(SMALL, 'GET', 'gmail', 'act_1', {});
-        assert.equal(r.wrap, true);
         assert.equal(r.text, SMALL);
         assert.equal(r.structured.truncated, false);
     });
     it('section wins over full when both are set', () => {
         const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { section: 'Response Fields', full: true });
-        assert.equal(r.wrap, false);
         assert.notEqual(r.text, LARGE);
         assert.ok(r.text.includes('Response Fields field 100'));
     });
 });
+describe('execute-mode knowledge text', () => {
+    it('carries no raw-HTTP request guidance', () => {
+        for (const options of [{}, { full: true }, { section: 'Method' }, { toc: true }]) {
+            const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', options);
+            assert.doesNotMatch(r.text, /API REQUEST STRUCTURE|x-one-secret|\/v1\/passthrough/);
+        }
+    });
+});

package/build/path-variables.test.js

@@ -0,0 +1,26 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { replacePathVariables } from './helpers.js';
+describe('replacePathVariables', () => {
+    it('fills exact names in both bracket styles', () => {
+        assert.equal(replacePathVariables('/tickets/{{ticketId}}/comments/{id}', { ticketId: 42, id: 'c 1' }), '/tickets/42/comments/c%201');
+    });
+    it('matches a variable regardless of case, underscores and hyphens', () => {
+        for (const key of ['ticket_id', 'TICKET_ID', 'ticket-id', 'TicketId']) {
+            assert.equal(replacePathVariables('/api/v2/tickets/{{ticketId}}', { [key]: 48213 }), '/api/v2/tickets/48213', key);
+        }
+        assert.equal(replacePathVariables('/repos/{owner}/{repo}/pulls/{{pullNumber}}', { owner: 'acme', repo: 'web', pull_number: 517 }), '/repos/acme/web/pulls/517');
+    });
+    it('prefers the exact name over a loose match', () => {
+        assert.equal(replacePathVariables('/x/{{ticketId}}', { ticket_id: 'loose', ticketId: 'exact' }), '/x/exact');
+    });
+    it('names every expected variable when one is missing', () => {
+        assert.throws(() => replacePathVariables('/repos/{{owner}}/{{repo}}/pulls/{{pullNumber}}', { owner: 'acme', repo: 'web' }), /Missing value for path variable: pullNumber\..*pass pathVariables with: owner, repo, pullNumber\./);
+    });
+    it('leaves a path without variables untouched, even with no variables given', () => {
+        assert.equal(replacePathVariables('/v1/gmail/send-email', {}), '/v1/gmail/send-email');
+    });
+    it('rejects empty values', () => {
+        assert.throws(() => replacePathVariables('/x/{{id}}', { id: '' }), /Missing value for path variable: id/);
+    });
+});

package/build/schemas.js

@@ -16,16 +16,16 @@ export const listOneIntegrationsInputSchema = {};
  * Schema for searching platform actions
  */
 export const searchOnePlatformActionsInputSchema = {
-    platform: z.string().describe("The platform name to search actions for (e.g., 'ship-station', 'shopify'). This is the kebab-case version of the platform name that comes from the list_one_integrations tool AVAILABLE PLATFORMS section."),
+    platform: z.string().describe("The platform name to search actions for (e.g., 'ship-station', 'shopify'). This is the kebab-case platform name from list_one_integrations."),
     query: z.string().describe("The search query to find relevant actions (e.g., 'search contacts', 'create customer', 'send email'). Be specific about what you want to do."),
-    agentType: z.enum(["execute", "knowledge"]).optional().describe("The type of agent context: 'execute' if the user wants to execute an action, 'knowledge' if they want to get information or write code. Defaults to 'knowledge' if not specified.")
+    agentType: z.enum(["execute", "knowledge"]).optional().describe("The type of agent context: 'execute' if the user wants to execute an action, 'knowledge' if they want to get information or write code. Defaults to 'execute' when this server can execute actions (knowledge-only servers always use 'knowledge').")
 };
 /**
  * Schema for getting action knowledge
  */
 export const getOneActionKnowledgeInputSchema = {
     actionId: z.string().describe("The action ID to get knowledge for (from the actions list returned by search_one_platform_actions). REQUIRED: This tool must be called before execute_one_action to load the action's documentation into context."),
-    platform: z.string().describe("The platform name to get knowledge for (e.g., 'ship-station', 'shopify'). This is the kebab-case version of the platform name that comes from the list_one_integrations tool AVAILABLE PLATFORMS section."),
+    platform: z.string().describe("The platform name to get knowledge for (e.g., 'ship-station', 'shopify'). This is the kebab-case platform name from list_one_integrations."),
     section: z.string().optional().describe("Load specific section(s) of the documentation by name (e.g. 'Response Fields', or comma-separated 'Response Fields, Optional Request Body Fields'). Large docs return a digest first; use this on a follow-up call to pull a section the digest omitted."),
     full: z.boolean().optional().describe("Return the entire documentation verbatim instead of the token-saving digest. Ignored when `section` is set. Leave unset by default; only set it when you genuinely need every section."),
     toc: z.boolean().optional().describe("Return only the table of contents (every section's id, heading, and size), no bodies. Use it to see everything available when the digest collapsed its list. Ignored when `section` is set.")
@@ -75,11 +75,11 @@ export const listOneIntegrationsOutputSchema = {
         platform: z.string(),
         name: z.string(),
         category: z.string()
-    })).describe("Array of available platforms that can be connected"),
+    })).optional().describe("Platforms that can be connected. Only listed in knowledge/code-gen mode"),
     summary: z.object({
         connectedCount: z.number(),
-        availableCount: z.number()
-    }).describe("Summary statistics of connections and available platforms")
+        availableCount: z.number().optional()
+    }).describe("Counts of connections (and available platforms in knowledge/code-gen mode)")
 };
 /**
  * Output schemas for search_one_platform_actions tool
@@ -102,7 +102,7 @@ export const searchOnePlatformActionsOutputSchema = {
  */
 export const listOneIntegrationsToolConfig = {
     title: "List One Integrations",
-    description: "List all available One integrations and platforms. ALWAYS call this tool first in any workflow to discover what platforms and connections are available. This returns the connections that the user has and all available One platforms in kebab-case format (e.g., 'ship-station', 'shopify') which you'll need for subsequent tool calls. Each connection carries an `access` field describing what you may run on it: `full`, a set of allowed HTTP `methods`, or a specific list of `actions` (each with `actionId`, `title`, `method`). When a connection is action-scoped, its `actions` are exactly what may run, so you need not search.",
+    description: "List the platforms the user has connected on One. ALWAYS call this tool first in any workflow. Each connection has the kebab-case `platform` name (e.g., 'ship-station', 'shopify') and the `key` (the connectionKey for execute_one_action) you'll need for subsequent tool calls. Each connection carries an `access` field describing what you may run on it: `full`, a set of allowed HTTP `methods`, or a specific list of `actions` (each with `actionId`, `title`, `method`). When a connection is action-scoped, its `actions` are exactly what may run, so you need not search.",
     inputSchema: listOneIntegrationsInputSchema,
     outputSchema: listOneIntegrationsOutputSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A Model Context Protocol Server for One",
   "type": "module",
   "bin": {