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 for what a workspace exposes.
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-decodedYou 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.
ToolsClient
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.
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:
--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.
Last updated
Was this helpful?

