@withone/mcp 2.2.0 → 2.3.0

package/README.md

@@ -20,7 +20,7 @@
   <a href="https://npmjs.com/package/@withone/mcp"><img src="https://img.shields.io/npm/v/%40withone%2Fmcp" alt="npm version"></a>
 </p>
 
-Connect your AI agents to 700+ apps through a single [MCP](https://modelcontextprotocol.io) server. Find the actions a task needs with their documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
+Connect your AI agents to 1000+ apps through a single [MCP](https://modelcontextprotocol.io) server. Find the actions a task needs with their documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
 
 ```bash
 npm install -g @withone/cli
@@ -31,7 +31,7 @@ That's it. The [One CLI](https://www.npmjs.com/package/@withone/cli) will prompt
 
 ## Capabilities
 
-- **700+ platforms.** Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and [more](https://app.withone.ai/tools).
+- **1000+ platforms.** Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and [more](https://app.withone.ai/tools).
 - **Natural language execution.** "read my last gmail email", "send a message to #general on Slack"
 - **Code generation.** "build a form to send emails using Gmail", "create a dashboard that lists my Linear projects"
 - **No tool bloat.** Only 3 tools exposed regardless of how many platforms or actions you connect. One call finds every action a task needs, across platforms, with its documentation, so your agent's context window stays clean.

package/build/client.js

@@ -10,8 +10,18 @@ import axios from 'axios';
 import FormData from 'form-data';
 import { callerHeaders } from './caller.js';
 import { fetchPaginatedData, replacePathVariables } from './helpers.js';
+import { ToolError, oneApiError, oneRefusal } from './tool-error.js';
 /** Header names that only the server may set on an outgoing request. */
 const RESERVED_HEADER_PREFIX = 'x-one-';
+/** The prefix One renames every upstream response header to, so its presence marks a response the platform gave. */
+const PLATFORM_HEADER_PREFIX = 'x-passthrough-';
+/**
+ * Whether a passthrough response came from the platform rather than from One
+ * refusing the call before it reached the platform.
+ */
+export function answeredByPlatform(headers) {
+    return Object.keys(headers).some((name) => name.toLowerCase().startsWith(PLATFORM_HEADER_PREFIX));
+}
 /**
  * Drops any caller-supplied header that One itself controls (`x-one-secret`,
  * `x-one-connection-key`, `x-one-action-id`, ...). Comparison is
@@ -194,7 +204,7 @@ export class OneClient {
      * @param caller - The MCP client that connected and the model it named,
      *   sent so One records who asked
      * @returns One answer per intent, in the order asked
-     * @throws {Error} Naming core's reason when it refuses the request
+     * @throws {ToolError} Naming core's reason when it refuses the request
      */
     async findActions(requests, task, knowledgeAgent, caller = {}) {
         try {
@@ -203,22 +213,18 @@ export class OneClient {
         }
         catch (error) {
             console.error("Error finding actions:", describeError(error));
-            if (axios.isAxiosError(error)) {
-                const reason = error.response?.data?.message;
-                throw new Error(`Failed to find actions: ${reason ?? `${error.response?.status} ${error.response?.statusText}`}`);
-            }
-            throw new Error("Failed to find actions");
+            throw oneApiError("Failed to find actions", error);
         }
     }
     /**
      * Gets full action details by ID
      * @param actionId - The action ID to get details for
      * @returns The full action object
-     * @throws {Error} If action ID is not provided or API request fails
+     * @throws {ToolError} If the action ID is missing or unknown, or the API request fails
      */
     async getActionDetails(actionId) {
         if (!actionId?.trim()) {
-            throw new Error("Action ID is required");
+            throw new ToolError("An actionId is required. Use one returned by find_one_actions.");
         }
         const cached = this.actionDetailsCache.get(actionId);
         if (cached && cached.expiresAt > Date.now()) {
@@ -236,7 +242,7 @@ export class OneClient {
             });
             const actions = response.data?.rows || [];
             if (actions.length === 0) {
-                throw new Error(`Action with ID ${actionId} not found`);
+                throw new ToolError(`Action ${actionId} not found. Use an actionId returned by find_one_actions.`);
             }
             this.actionDetailsCache.set(actionId, {
                 details: actions[0],
@@ -245,11 +251,11 @@ export class OneClient {
             return actions[0];
         }
         catch (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}`);
+            if (error instanceof ToolError) {
+                throw error;
             }
-            throw new Error("Failed to fetch action details");
+            console.error("Error fetching action details:", describeError(error));
+            throw oneApiError("Failed to fetch action details", error);
         }
     }
     /**
@@ -293,8 +299,8 @@ export class OneClient {
     /**
      * Executes a passthrough request to a third-party API through One
      * @param args - The execution arguments containing all request details
-     * @returns Object containing sanitized request config and response data
-     * @throws {Error} If the request fails
+     * @returns The platform's response, whatever its status, with the sanitized request config
+     * @throws {ToolError} If One refuses the call or cannot be reached
      */
     async executePassthroughRequest(args, preloadedAction) {
         const { actionId, connectionKey, data, pathVariables, queryParams, headers, isFormData, isFormUrlEncoded, } = args;
@@ -385,20 +391,25 @@ export class OneClient {
                 'x-one-secret': '***REDACTED***'
             }
         };
+        let response;
         try {
-            const response = await axios(requestConfig);
-            return {
-                requestConfig: sanitizedConfig,
-                responseData: response.data
-            };
+            // Every status resolves: a platform's 4xx or 5xx is its answer, which
+            // the agent reads; only One refusing the call is a tool error.
+            response = await axios({ ...requestConfig, validateStatus: () => true });
         }
         catch (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}`);
-            }
-            throw new Error("Failed to execute passthrough request");
+            throw oneApiError("Failed to execute One action", error, true);
+        }
+        if (response.status >= 400 && !answeredByPlatform(response.headers)) {
+            console.error("One refused the passthrough request:", { status: response.status, url: url.split('?')[0], data: summarizeErrorData(response.data) });
+            throw oneRefusal("Failed to execute One action", response.status, response.data);
         }
+        return {
+            responseData: response.data,
+            status: response.status,
+            requestConfig: sanitizedConfig
+        };
     }
     /**
      * Gets the base URL for the One API

package/build/client.test.js

@@ -1,7 +1,8 @@
 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';
+import { OneClient, stripReservedHeaders, describeError, answeredByPlatform } from './client.js';
+import { ToolError } from './tool-error.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';
@@ -16,13 +17,13 @@ describe("executePassthroughRequest keeps One's headers authoritative", () => {
     let server;
     let base = '';
     let received = [];
-    let failBody = null;
+    let reply = 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);
+            if (reply !== null) {
+                res.writeHead(reply.status, { 'Content-Type': 'application/json', ...reply.headers });
+                res.end(reply.body);
                 return;
             }
             res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -36,7 +37,7 @@ describe("executePassthroughRequest keeps One's headers authoritative", () => {
     });
     beforeEach(() => {
         received = [];
-        failBody = null;
+        reply = null;
     });
     it('a caller cannot override the x-one-* routing/auth headers', async () => {
         const client = new OneClient(SECRET, base);
@@ -68,8 +69,41 @@ describe("executePassthroughRequest keeps One's headers authoritative", () => {
         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) });
+    it("a platform's 4xx or 5xx is returned as its answer, with the status and body", async () => {
+        const client = new OneClient(SECRET, base);
+        for (const status of [404, 500]) {
+            reply = { status, headers: { 'X-Passthrough-Content-Type': 'application/json' }, body: JSON.stringify({ error: 'no such contact' }) };
+            const result = await client.executePassthroughRequest(exec({}), ACTION);
+            assert.equal(result.status, status);
+            assert.deepEqual(result.responseData, { error: 'no such contact' });
+            assert.deepEqual(Object.keys(result).slice(0, 2), ['responseData', 'status'], 'the payload leads');
+        }
+    });
+    it("a call One refuses throws a tool error with One's reason and reference", async () => {
+        reply = {
+            status: 404,
+            body: JSON.stringify({ type: 'passthrough_error', status: 404, key: 'not_found', message: 'Connection not found', correlation_id: 'corr-1' }),
+        };
+        const client = new OneClient(SECRET, base);
+        await assert.rejects(client.executePassthroughRequest(exec({}), ACTION), (e) => e instanceof ToolError && e.message.includes('Connection not found') && e.message.includes('corr-1'));
+    });
+    it('One being unreachable is a tool error that warns against a blind retry', async () => {
+        const closed = http.createServer();
+        await new Promise((resolve) => closed.listen(0, '127.0.0.1', () => resolve()));
+        const port = closed.address().port;
+        await new Promise((resolve) => closed.close(() => resolve()));
+        const client = new OneClient(SECRET, `http://127.0.0.1:${port}`);
+        const original = console.error;
+        console.error = () => { };
+        try {
+            await assert.rejects(client.executePassthroughRequest(exec({}), ACTION), (e) => e instanceof ToolError && /could not be reached/.test(e.message) && /check whether it took effect/.test(e.message));
+        }
+        finally {
+            console.error = original;
+        }
+    });
+    it('a refused call never logs the secret, and bounds the body', async () => {
+        reply = { status: 422, body: JSON.stringify({ message: 'upstream said no', padding: 'x'.repeat(2000) }) };
         const client = new OneClient(SECRET, base);
         const logged = [];
         const original = console.error;
@@ -90,7 +124,14 @@ describe("executePassthroughRequest keeps One's headers authoritative", () => {
         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');
+        assert.ok(message.includes('422') && message.includes('upstream said no'), "the tool error carries the status and One's reason");
+    });
+});
+describe('answeredByPlatform', () => {
+    it('reads a renamed upstream header, in any casing, as the platform answering', () => {
+        assert.equal(answeredByPlatform({ 'x-passthrough-content-type': 'application/json' }), true);
+        assert.equal(answeredByPlatform({ 'X-Passthrough-Date': 'now' }), true);
+        assert.equal(answeredByPlatform({ 'content-type': 'application/json', 'x-one-correlation-id': 'c' }), false);
     });
 });
 describe('stripReservedHeaders', () => {

package/build/find.js

@@ -12,6 +12,7 @@
  * @fileoverview find_one_actions logic, free of HTTP so it can be tested
  * @author One
  */
+import { ToolError } from './tool-error.js';
 import { buildKnowledgeResponse, isActionAllowed, isMethodAllowed, platformEnvSegment } from './helpers.js';
 /** How many intents one find answers. Core enforces the same cap. */
 export const FIND_MAX_INTENTS = 10;
@@ -27,13 +28,10 @@ export const FIND_EXECUTE_HINT = 'Run it with `execute_one_action`: `platform`,
 export const REFUSED_LOAD = 'no such action, or this server may not use it';
 /** What a call that is neither a find nor a load is told. */
 export const FIND_ARGS_ERROR = 'Send either `requests` (to find actions, with an optional `task`) or `load` (for more documentation, without `task`), not both and not neither.';
-/** A call the agent has to fix, reported to it rather than failing the server. */
-export class FindArgsError extends Error {
-}
 /**
  * Answers a `find_one_actions` call: finds actions for `requests`, or serves
  * more documentation for `load`.
- * @throws {FindArgsError} When the call is neither, both, or `task` comes with `load`
+ * @throws {ToolError} When the call is neither, both, or `task` comes with `load`
  */
 export async function findOneActions(args, deps, settings) {
     if (args.requests && !args.load) {
@@ -42,7 +40,7 @@ export async function findOneActions(args, deps, settings) {
     if (args.load && !args.requests && args.task === undefined) {
         return load(args.load, deps, settings);
     }
-    throw new FindArgsError(FIND_ARGS_ERROR);
+    throw new ToolError(FIND_ARGS_ERROR);
 }
 /** An action as the agent refers to it: title, method, path and `actionId`. */
 export function actionHeading(title, method, path, actionId) {
@@ -150,7 +148,7 @@ function finish(sections, documented, settings) {
 }
 async function find(requests, task, deps, settings, caller) {
     if (requests.length === 0 || requests.length > FIND_MAX_INTENTS) {
-        throw new FindArgsError(`Send between 1 and ${FIND_MAX_INTENTS} requests.`);
+        throw new ToolError(`Send between 1 and ${FIND_MAX_INTENTS} requests.`);
     }
     const reachable = requests.filter((r) => reaches(settings, r.platform));
     const answers = reachable.length > 0 ? await deps.findActions(reachable, task, settings.knowledgeAgent, caller) : [];
@@ -267,7 +265,7 @@ function boundDocuments(plans, documents, settings) {
 }
 async function load(loads, deps, settings) {
     if (loads.length === 0 || loads.length > FIND_MAX_LOADS) {
-        throw new FindArgsError(`Send between 1 and ${FIND_MAX_LOADS} loads.`);
+        throw new ToolError(`Send between 1 and ${FIND_MAX_LOADS} loads.`);
     }
     const entries = await Promise.all(loads.map(async (entry) => {
         const refused = { text: `\`${entry.action_id}\`: ${REFUSED_LOAD}`, documented: false };

package/build/find.test.js

@@ -1,6 +1,7 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { FIND_ARGS_ERROR, FIND_EXECUTE_HINT, FindArgsError, REFUSED_LOAD, findOneActions, } from './find.js';
+import { FIND_ARGS_ERROR, FIND_EXECUTE_HINT, REFUSED_LOAD, findOneActions, } from './find.js';
+import { ToolError } from './tool-error.js';
 // Pure: core and the knowledge endpoint are stubbed, so no network is touched.
 const LARGE = [
     '# Send Email',
@@ -70,7 +71,7 @@ describe('find_one_actions', () => {
     });
     it('takes requests or load, never both, never neither, and no task with a load', async () => {
         for (const args of [{}, { requests: intent, load: [{ action_id: 'a' }] }, { load: [{ action_id: 'a' }], task: 't' }]) {
-            await assert.rejects(findOneActions(args, deps([answer()]), settings()), (e) => e instanceof FindArgsError && e.message === FIND_ARGS_ERROR);
+            await assert.rejects(findOneActions(args, deps([answer()]), settings()), (e) => e instanceof ToolError && e.message === FIND_ARGS_ERROR);
         }
     });
     it('names each action by actionId, documents the pick from its raw knowledge, and ends on the execute arguments once', async () => {

package/build/helpers.js

@@ -7,6 +7,7 @@
  * @author One
  */
 import axios from 'axios';
+import { ToolError } from './tool-error.js';
 import { parseSections, buildDigest, renderDigestBanner, renderDigestNotice, selectSections, flattenSections, parseSectionFlag, collapseSections, omittedSections, } from './knowledge-sections.js';
 /**
  * Paginates through API results by repeatedly calling a fetch function until all data is retrieved.
@@ -203,7 +204,7 @@ export function replacePathVariables(path, variables) {
         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: ${name}. This action's path is ${path}; pass pathVariables with: ${[...new Set(expected)].join(', ')}.`);
+            throw new ToolError(`Missing value for path variable: ${name}. This action's path is ${path}; pass pathVariables with: ${[...new Set(expected)].join(', ')}.`);
         }
         return encodeURIComponent(value.toString());
     };

package/build/index.js

@@ -12,10 +12,12 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { OneClient } from './client.js';
 import { isMethodAllowed, isActionAllowed, buildIntegrationsResponse, } from './helpers.js';
-import { FindArgsError, findOneActions } from './find.js';
+import { findOneActions } from './find.js';
+import { ToolError, toolErrorResult } from './tool-error.js';
 import { listOneIntegrationsToolConfig, findOneActionsToolConfig, executeOneActionToolConfig } from './schemas.js';
+import { createRequire } from 'node:module';
 const SERVER_NAME = "one-mcp-server";
-const SERVER_VERSION = "1.0.0";
+const SERVER_VERSION = createRequire(import.meta.url)('../package.json').version;
 const ONE_SECRET = process.env.ONE_SECRET;
 if (!ONE_SECRET) {
     console.error("ONE_SECRET environment variable is required");
@@ -93,7 +95,7 @@ async function handleGetIntegrations(args) {
         const resolvedAllowed = (await oneClient.resolveAllowedActions(ONE_ACTION_IDS))
             .filter(action => isMethodAllowed(action.method, ONE_PERMISSIONS));
         // Execute mode lists only connections: every connection carries its
-        // access, and the full catalog (800+ platforms) would sit in the agent's
+        // access, and the full catalog (1000+ 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.
@@ -137,11 +139,8 @@ async function handleFindOneActions(args) {
     catch (error) {
         // A call the agent has to fix goes back to it as a tool error it can read
         // and correct, rather than a protocol failure.
-        if (error instanceof FindArgsError) {
-            return {
-                content: [{ type: "text", text: error.message }],
-                isError: true,
-            };
+        if (error instanceof ToolError) {
+            return toolErrorResult(error);
         }
         throw new McpError(ErrorCode.InternalError, `Failed to find actions: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
@@ -149,17 +148,17 @@ async function handleFindOneActions(args) {
 async function handleExecuteOneAction(args) {
     try {
         if (!isActionAllowed(args.actionId, ONE_ACTION_IDS)) {
-            throw new McpError(ErrorCode.InvalidRequest, `Action "${args.actionId}" is not in the allowed action list`);
+            throw new ToolError(`Action "${args.actionId}" is not one this server may run. Use an action listed in list_one_integrations or returned by find_one_actions.`);
         }
         if (!ONE_CONNECTION_KEYS.includes("*")) {
             const allowedKeys = oneClient.getUserConnections().map(c => c.key);
             if (!allowedKeys.includes(args.connectionKey)) {
-                throw new McpError(ErrorCode.InvalidRequest, `Connection key "${args.connectionKey}" is not allowed`);
+                throw new ToolError(`Connection key "${args.connectionKey}" is not one this server may use. Use a connection key from list_one_integrations.`);
             }
         }
         const actionDetails = await oneClient.getActionDetails(args.actionId);
         if (!isMethodAllowed(actionDetails.method, ONE_PERMISSIONS)) {
-            throw new McpError(ErrorCode.InvalidRequest, `Method "${actionDetails.method}" is not allowed under "${ONE_PERMISSIONS}" permission level`);
+            throw new ToolError(`Action "${args.actionId}" is a ${actionDetails.method.toUpperCase()} request, which this server's "${ONE_PERMISSIONS}" permission level does not allow, so it cannot be run here.`);
         }
         const result = await oneClient.executePassthroughRequest(args, actionDetails);
         return {
@@ -169,9 +168,13 @@ async function handleExecuteOneAction(args) {
                     text: JSON.stringify(result, null, 2),
                 },
             ],
+            structuredContent: result,
         };
     }
     catch (error) {
+        if (error instanceof ToolError) {
+            return toolErrorResult(error);
+        }
         throw new McpError(ErrorCode.InternalError, `Failed to execute One action: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 }

package/build/schemas.js

@@ -34,15 +34,30 @@ export const findOneActionsInputSchema = {
  * Schema for executing One actions
  */
 export const executeOneActionInputSchema = {
-    platform: z.string().describe("Platform name"),
-    actionId: z.string().describe("The actionId from find_one_actions"),
-    connectionKey: z.string().describe("Key of the connection to use"),
-    data: z.any().optional().describe("Request data (for POST, PUT, etc.)"),
-    pathVariables: z.record(z.union([z.string(), z.number(), z.boolean()])).optional().describe("Variables to replace in the path"),
-    queryParams: z.record(z.any()).optional().describe("Query parameters"),
-    headers: z.record(z.string()).optional().describe("Additional headers"),
-    isFormData: z.boolean().optional().describe("Whether to send data as multipart/form-data"),
-    isFormUrlEncoded: z.boolean().optional().describe("Whether to send data as application/x-www-form-urlencoded")
+    platform: z.string().describe('The kebab-case platform of the connection (e.g. "gmail"), as list_one_integrations names it.'),
+    actionId: z.string().describe("The actionId of the action to run, as returned when the action was found (or from the connection's `access` list)."),
+    connectionKey: z.string().describe("The connection key for the caller's connection (from list_one_integrations)."),
+    data: z.any().optional().describe("The request body. JSON by default; encoded as form data when isFormData or isFormUrlEncoded is set."),
+    pathVariables: z.record(z.union([z.string(), z.number(), z.boolean()])).optional().describe("Substitutions for {var} / {{var}} placeholders in the action path."),
+    queryParams: z.record(z.any()).optional().describe("Query-string parameters appended to the request."),
+    headers: z.record(z.string()).optional().describe("Extra request headers to forward to the upstream platform."),
+    isFormData: z.boolean().optional().describe("Encode the body as multipart/form-data."),
+    isFormUrlEncoded: z.boolean().optional().describe("Encode the body as application/x-www-form-urlencoded.")
+};
+/**
+ * Output schema for execute_one_action. `responseData` comes first so a client
+ * that cuts long output short still shows the payload.
+ */
+export const executeOneActionOutputSchema = {
+    responseData: z.any().describe("The platform's response body, whatever its status."),
+    status: z.number().describe("The platform's HTTP status. A 4xx or 5xx is the platform's answer: read `responseData` for its reason."),
+    requestConfig: z.object({
+        url: z.string(),
+        method: z.string(),
+        headers: z.record(z.string()),
+        params: z.record(z.any()).optional(),
+        data: z.any().optional()
+    }).describe("The request as sent, with the One secret redacted.")
 };
 /**
  * Output schemas for list_one_integrations tool
@@ -81,6 +96,16 @@ export const listOneIntegrationsOutputSchema = {
         availableCount: z.number().optional()
     }).describe("Counts of connections (and available platforms in knowledge/code-gen mode)")
 };
+/**
+ * Hints for a tool that only reads One's own data, matching the remote MCP's:
+ * clients may run it without asking the user.
+ */
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+};
 /**
  * Tool configuration objects for registerTool
  */
@@ -88,17 +113,26 @@ export const listOneIntegrationsToolConfig = {
     title: "List One Integrations",
     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
+    outputSchema: listOneIntegrationsOutputSchema,
+    annotations: READ_ONLY_ANNOTATIONS
 };
 export const findOneActionsToolConfig = {
     title: "Find Platform Actions",
     description: "Use this to find the API actions a task needs, on any platforms, in one call: send one `requests` entry per operation (platform and a short intent) and get back, for each, the action to use with its documentation, plus a few alternatives. Large documents come back as a digest; call again with `load` for a section it omitted, the whole document, the table of contents, or an alternative's documentation. Results are limited to what this server's settings allow. Call list_one_integrations first to see the connected platforms.",
-    inputSchema: findOneActionsInputSchema
+    inputSchema: findOneActionsInputSchema,
+    annotations: READ_ONLY_ANNOTATIONS
 };
 export const executeOneActionToolConfig = {
     title: "Execute One Action",
     description: "Execute a One action to perform actual operations on third-party platforms. CRITICAL: Only call this when the user's intent is to EXECUTE an action (e.g., 'read my last Gmail email', 'fetch 5 contacts from HubSpot', 'create a task in Asana'). DO NOT call this when the user wants to BUILD or CREATE code/forms/applications - in those cases, stop after find_one_actions and provide implementation guidance instead. REQUIRED WORKFLOW: Must call find_one_actions first, which returns the action's documentation. If uncertain about execution intent or parameters, ask for confirmation before proceeding.",
-    inputSchema: executeOneActionInputSchema
+    inputSchema: executeOneActionInputSchema,
+    outputSchema: executeOneActionOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+    }
 };
 /**
  * Zod object schemas for type inference (for internal use)

package/build/schemas.test.js

@@ -0,0 +1,63 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { executeOneActionToolConfig, findOneActionsToolConfig, listOneIntegrationsToolConfig, } from './schemas.js';
+import { ToolError, toolErrorResult } from './tool-error.js';
+// The hints and the execute output schema match the remote MCP's, so a client
+// treats a tool the same on either surface.
+const PLATFORM_404 = {
+    responseData: { error: 'no such contact' },
+    status: 404,
+    requestConfig: { url: 'https://api.withone.ai/v1/passthrough/contacts/1', method: 'GET', headers: { 'x-one-secret': '***REDACTED***' } },
+};
+/** A client connected to a server offering the three tools, execute answering with `execute`. */
+async function connect(execute) {
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    server.registerTool('list_one_integrations', listOneIntegrationsToolConfig, async () => ({
+        content: [],
+        structuredContent: { connections: [], summary: { connectedCount: 0 } },
+    }));
+    server.registerTool('find_one_actions', findOneActionsToolConfig, async () => ({ content: [] }));
+    server.registerTool('execute_one_action', executeOneActionToolConfig, async () => execute());
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'test-client', version: '0.0.0' });
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    return client;
+}
+const CALL = { name: 'execute_one_action', arguments: { platform: 'hubspot', actionId: 'a', connectionKey: 'k' } };
+describe('tool annotations', () => {
+    it('mark execute destructive and open-world, and the rest read-only', async () => {
+        const client = await connect(() => ({ content: [], structuredContent: PLATFORM_404 }));
+        const { tools } = await client.listTools();
+        assert.equal(tools.length, 3);
+        for (const tool of tools) {
+            const hints = tool.annotations;
+            assert.ok(hints && hints.readOnlyHint !== undefined && hints.openWorldHint !== undefined, `${tool.name} sets its hints`);
+            if (tool.name === 'execute_one_action') {
+                assert.deepEqual([hints.readOnlyHint, hints.destructiveHint, hints.idempotentHint, hints.openWorldHint], [false, true, false, true]);
+            }
+            else {
+                assert.deepEqual([hints.readOnlyHint, hints.destructiveHint, hints.idempotentHint, hints.openWorldHint], [true, false, true, false], `${tool.name} is read-only`);
+            }
+        }
+    });
+});
+describe('execute_one_action output', () => {
+    it("accepts a platform's 404 as a result, not an error", async () => {
+        const client = await connect(() => ({
+            content: [{ type: 'text', text: JSON.stringify(PLATFORM_404) }],
+            structuredContent: PLATFORM_404,
+        }));
+        const result = await client.callTool(CALL);
+        assert.equal(result.isError, undefined);
+        assert.deepEqual(result.structuredContent, PLATFORM_404);
+    });
+    it('reports a tool error as an isError result the agent reads', async () => {
+        const client = await connect(() => toolErrorResult(new ToolError('Connection key "k" is not one this server may use.')));
+        const result = await client.callTool(CALL);
+        assert.equal(result.isError, true);
+        assert.deepEqual(result.content, [{ type: 'text', text: 'Connection key "k" is not one this server may use.' }]);
+    });
+});

package/build/tool-error.js

@@ -0,0 +1,47 @@
+/**
+ * Tool errors the agent reads and acts on
+ *
+ * A refusal, a missing argument, or One being unreachable is reported to the
+ * agent as an `isError` tool result, which every MCP client shows the model.
+ * A protocol error is reserved for a fault in this server itself.
+ *
+ * @fileoverview The tool-error type and how One API failures become one
+ * @author One
+ */
+import axios from 'axios';
+/** A failure the agent can read and correct, returned as an `isError` result rather than a protocol error. */
+export class ToolError extends Error {
+}
+/** The `isError` result a ToolError is reported as. */
+export function toolErrorResult(error) {
+    return {
+        content: [{ type: "text", text: error.message }],
+        isError: true,
+    };
+}
+/**
+ * Reports a response One itself refused, with its reason and the reference
+ * support can trace it by.
+ * @param what - What was being done, e.g. "Failed to execute One action"
+ */
+export function oneRefusal(what, status, body) {
+    const { message, correlation_id } = (body && typeof body === 'object' ? body : {});
+    const reason = message ?? `status ${status}`;
+    const reference = correlation_id ? `, reference: ${correlation_id}` : '';
+    return new ToolError(`${what}: ${reason} (One answered ${status}${reference}).`);
+}
+/**
+ * Reports a failed call to the One API: One's reason when it answered, or that
+ * it did not answer.
+ * @param what - What was being done, e.g. "Failed to find actions"
+ * @param mayHaveRun - The call could have reached the platform, so a write must be checked before it is tried again
+ */
+export function oneApiError(what, error, mayHaveRun = false) {
+    if (axios.isAxiosError(error) && error.response) {
+        return oneRefusal(what, error.response.status, error.response.data);
+    }
+    const retry = mayHaveRun
+        ? 'If this call changes data, check whether it took effect before trying again; otherwise try again.'
+        : 'Try again.';
+    return new ToolError(`${what}: One could not be reached. ${retry}`);
+}

package/package.json

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