> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/reference/sdk/workspace-tools.md).

# Workspace tools

The optional route: list and run the MCP tools your fastn workspace has turned on, with ToolsClient.

You do not need this page for the flows in the rest of this section. It is an optional second route: if your app or AI agent works with **tools by name** (as an MCP client does), `ToolsClient` lists and runs the tools your fastn workspace has turned on, with the customer set on each call. See [MCP gateway](https://docs.fastn.ai/build/building-from-your-ai-agent/mcp-gateway.md) for what a workspace exposes.

```typescript
import { ToolsClient, ToolError } from "@fastn-ai/sdk";

const tools = new ToolsClient({
  key: process.env.FASTN_TOOLS_KEY!,
  url: "https://mcp.fastn.dev/your-workspace",
});

const all = await tools.tools();                       // every tool, with its input schema
const calendar = await tools.toolsOf("googleCalendar"); // one app's tools

const r = await tools.customer("acme_customer_42").call("googleCalendar__listCalendars", {});
console.log(r.data);                                    // the tool's answer, JSON-decoded
```

You can also give `FastnClient` a `tools: { key, url }` option. Then `fastn.tools` is a `ToolsClient`, and `fastn.customer(ref).tools` is the same client set to that customer.

{% hint style="info" %}
The workspace key is a different credential from your fastn platform API key. Keep both in your secret store.
{% endhint %}

### ToolsClient

| Option        | Required | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`         | Yes      | The workspace key. Sent as `Authorization: Bearer`.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `url`         | Yes      | The workspace endpoint.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `timeoutMs`   | No       | Time limit per call. Default 120000 (tools can be slow).                                                                                                                                                                                                                                                                                                                                                                                              |
| `defaults`    | No       | Options for every call, for example `{ customer: { ref: "acme_customer_42" } }`.                                                                                                                                                                                                                                                                                                                                                                      |
| `customerArg` | No       | Default `true`: a call scoped to a customer fills your customer id into the Fastn Workspace tools that take it, so the customer is named once; `orgId` in the arguments reaches every Fastn Workspace tool that takes a customer, so you write `orgId` everywhere; and Fastn Workspace answers come back without fastn's internal customer id, so the only customer id you see is yours (`r.text` keeps the raw answer). `false` turns all three off. |

| Method                    | Answer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tools()`                 | Every tool: `[ { name, title, description, inputSchema, annotations } ]`. Tool names look like `<app>__<action>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `toolsOf(app)`            | The tools of one app.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `customer(ref)`           | The same client, sending `X-Org-Id: ref` on every call and filling `ref` into the Fastn Workspace tools that take a customer argument (the unified record tools). The tool schemas come from one `tools()` listing per workspace, shared by every `customer()` client; after 10 minutes a call still goes out at once with the cached schemas and one refresh runs in the background. Call `tools()` once at startup if the first call must not pay for the listing. A call is never sent without the customer on a guess: when the listing fails or comes back empty, the call throws that error (and the next call lists again); a `fastnPlatform__*` tool missing from the cached map triggers one fresh listing, then an unknown-tool `ToolError`. A customer you pass in the arguments yourself wins. Register webhooks from a client with no customer: on `fastnPlatform__createEventSubscription` the customer id (`orgId`) is a filter, and a subscription made with it only receives that one customer's events. With `customerArg` on, the answers of the subscription tools come back without that field, so the filter shows only in `r.text` or with `customerArg: false`. |
| `call(name, args, opts?)` | `{ data, text, content, structuredContent, isError }`. `data` is the answer JSON-decoded when it parses; `text` is the raw text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `rpc(method, params)`     | A raw JSON-RPC call, for methods the client does not wrap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

Per-call options: `customer`, `userId` (sent as `X-User-Id`, when the workspace runs calls as each person), `headers`, `timeoutMs`, `signal`, `retries` (default `0`, because the SDK cannot know whether a tool is safe to repeat; turn it on for reads).

### Typed methods for your workspace: `npx fastn-sdk-tools`

Tool names as strings work, but your editor cannot check them. The generator turns your workspace's tool list into one TypeScript module with a class per app and a method per tool, each input typed from the tool's schema:

```bash
# once, and again whenever the workspace changes (commit the file)
export FASTN_TOOLS_KEY=...                                        # the workspace key; it never ends up in the file
npx fastn-sdk-tools --url https://mcp.fastn.dev/<workspace> --out src/fastn-tools.ts
npx fastn-sdk-tools --url https://mcp.fastn.dev/<workspace> --out src/fastn-tools.ts --check   # CI: exit 1 on drift
```

```typescript
import { ToolsClient } from "@fastn-ai/sdk";
import { createTools } from "./fastn-tools.js";

const tools = createTools(new ToolsClient({ key: process.env.FASTN_TOOLS_KEY!, url: "https://mcp.fastn.dev/<workspace>" }));

const acme = tools.customer("acme_customer_42");
const cals = await acme.googleCalendar.listCalendars({});
const created = await acme.hubspot.createContact({ email: "jane@example.com", firstname: "Jane" });   // typed from the schema
```

| Option                                                     | Meaning                                                                                             |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `--url`, `--key` (or `FASTN_TOOLS_URL`, `FASTN_TOOLS_KEY`) | Fetch the tool list from the workspace. The file records the url and the tool count, never the key. |
| `--from tools-list.json`                                   | Generate offline from a saved tool list. The same list gives the same file.                         |
| `--customer <ref>`                                         | Fetch the list as that customer.                                                                    |
| `--out <file.ts>`                                          | Where to write.                                                                                     |
| `--check`                                                  | Exit 1 when the file would change.                                                                  |

The module exports `createTools`, one class per app (`GoogleCalendarTools`), one input interface per tool (`GoogleCalendarListEventsInput`), an output type where the tool publishes one, and `TOOL_NAMES`. Names become identifiers (`google-calendar` → `googleCalendar`); property names stay as the schema spells them. `tools.client` is the `ToolsClient` underneath, for a tool the file does not know yet. Answers and errors are the same `ToolResult` and `ToolError` as `call()`.

### ToolError

Failures throw `ToolError`.

| `kind` | Means                                                                          |
| ------ | ------------------------------------------------------------------------------ |
| `http` | The gateway answered with a non-2xx status, for example `401` for a wrong key. |
| `rpc`  | A JSON-RPC error, for example an unknown tool.                                 |
| `tool` | The tool ran and answered with an error.                                       |
| `auth` | The app behind the tool is not connected for this customer yet.                |

Other fields: `status`, `code`, `tool`, `body`, and the shortcuts `isAuth`, `isUnknownTool` and `isConnectionRequired`. For kind `auth`, `isConnectionRequired` is `true`, `authorizeUrl` is where to send the customer to connect, and `connector` names the app.

{% hint style="warning" %}
Today the gateway reports an app refusal (a record id that does not exist, a value the app rejects) as a tool error whose message is only `error code: 502`, the same text as a real upstream hiccup. The app's own message is on its way (platform ticket KAT-8586). Until then: the SDK counts that message as a hiccup, so with `retries` on it has already retried it; a 502 that still comes back is the app refusing the request, so check the id or the value rather than retrying further.
{% endhint %}

```typescript
import { ToolError } from "@fastn-ai/sdk";

try {
  await tools.customer("acme_customer_42").call("hubspot__getContact", { contactId: "51234567890" });
} catch (e) {
  if (e instanceof ToolError && e.isConnectionRequired) {
    console.log("ask the customer to connect", e.connector, "at", e.authorizeUrl);
  } else {
    throw e;
  }
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fastn.ai/reference/sdk/workspace-tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
