Build apps with Swirls

Swirls provides the backend for your business software: workflows, agents, data, integrations, and managed execution. You build the application people use, with the framework and interface that fit the job.

That application might be a React customer portal, a Node.js service, an API used by another business, or an MCP server that makes your workflows available in ChatGPT or Claude. Each uses Swirls behind the scenes. Your end users can use your software without opening Swirls Cloud.

Where Swirls fits

Your application defines the experience and the business actions people can take. Swirls runs the backend behavior you declare in your project.

You can also declare a hosted Swirls App when its pages, workflow launchers, chat, and review inboxes fit your needs. This is an optional interface to the same backend. A custom React app or MCP server does not require an app block.

Choose your interface

The same workflow can serve several interfaces. For example, a sales team can create a quote from a portal, an API integration, or a conversation in Claude, with the quote-generation rules maintained in one Swirls workflow.

Call a workflow from your application

First, deploy your project and configure OIDC federation for the users who will call it. Federation exchanges a JWT from your registered identity provider for a short-lived Swirls credential scoped to one project.

Install the TypeScript SDK in your application server:

npm install @swirls/sdk

This example assumes you have deployed a quote workflow whose entry node accepts { orderId: string }. It shows the Swirls call that a web route, API endpoint, or MCP tool handler can share:

import { createFederatedTokenSource } from '@swirls/sdk/auth'
import { Swirls } from '@swirls/sdk/client'

export function createQuoteService(options: {
  getSubjectToken: () => Promise<string>
  quoteWorkflowSnapshotId: string
}) {
  const swirls = new Swirls({
    apiKey: createFederatedTokenSource({
      getSubjectToken: options.getSubjectToken,
    }),
  })

  return {
    async createQuote(input: { orderId: string }) {
      const { executionId } = await swirls.client.workflows.executeWorkflow({
        workflowId: options.quoteWorkflowSnapshotId,
        input,
      })

      return { executionId }
    },
  }
}

Your server supplies getSubjectToken from the authenticated user's identity-provider session, with the audience registered for their project. Create a separate service and token source for each user and project; the token source caches credentials. Keep these credentials on your server.

Resolve quoteWorkflowSnapshotId from the deployment your application is intended to use. listRunnableWorkflows lists workflows for a project and deployment, including their entry-node input schemas. Its id field is the snapshot ID that executeWorkflow expects in workflowId. Inspect the schema when wiring the operation, and update the snapshot mapping when you release a new deployment.

Before calling createQuote, your route or tool handler must validate the input at runtime and check that the signed-in user can act on that order. Select the project and workflow from your server's configuration for that customer.

Return progress and results

Starting a workflow returns an executionId. The work may still be running, waiting for a review, or eventually fail. Use getExecution({ id: executionId }) to read its status, output, and error, then present the fields your application needs. For live updates, see the supported federated application calls.

Associate each execution with the user and business operation in your application. Standalone workflow runs are shared within a Swirls project, so your server must enforce any finer customer or user restrictions when returning status and results. See OIDC federation for the access boundary.

For a web app, this might mean a progress page. For an API, return a run identifier and a status endpoint. For MCP, return the run identifier and expose a tool that checks its progress. Report completion only after the execution has completed.

Let customers run workflows from ChatGPT or Claude

For workflows already declared in Swirls, use a managed MCP channel: list the workflows on the channel, grant access through policy, and assign trusted credential attributes in Cloud. Swirls hosts the tools, authenticates the credential, and handles durable execution and result polling.

Build your own MCP server when you need custom tool composition, application-specific authorization, or your own authentication flow. For the quote example, its tool contract could be:

These are example tools you implement in your MCP server. Choose names, descriptions, and input schemas that describe your customer's work. Map each tool to the workflow it is allowed to invoke; keep project and workflow selection in your server.

The request follows this path:

1. The customer asks ChatGPT or Claude to create a quote for an order.
2. The assistant calls your create_quote MCP tool.
3. Your server authenticates the caller, authorizes the order, and starts the Swirls workflow.
4. Swirls executes the workflow and records its progress and result.
5. The assistant uses your status tool to retrieve the result and present it in the conversation.

Host a remote MCP endpoint reachable by the client and configure its authentication. Authentication from ChatGPT or Claude to your MCP server is a separate connection from your server to Swirls. Your server must map the authenticated caller to an authorized customer and project, then obtain the appropriate Swirls credential. Configuring Swirls federation alone does not implement your MCP server's client authentication.

Connect your server using the client's setup instructions:

• ChatGPT: Add a custom MCP server. ChatGPT supports read and write MCP tools; availability is subject to workspace permissions and security restrictions.
• Claude: Set up a custom connector using remote MCP. Claude's remote connectors reach your server from Anthropic's infrastructure, so configure network access accordingly.

Test authentication, tool discovery, workflow execution, and result retrieval in each client you intend to support. If an operation requires a business approval, put that requirement in the workflow's review step so it applies through every interface.

How this relates to Swirls MCP channels

MCP channels can publish workflows as individual tools, expose a deployed Swirls agent through send_message, or offer both. Workflow tools reuse your workflow's description and input schema. The built-in get_execution tool returns status and results for runs owned by that credential.

Your own MCP server gives your application control over the external tool contract and identity mapping. A managed channel provides a declared, credential-scoped interface to your Swirls backend. Check the channel guide for client compatibility notes.

An mcp block is another connection: it lets an agent running in Swirls consume tools from an external MCP server.

Next steps

• SDK reference: call Swirls from TypeScript.
• Workflow API: discover workflows, start runs, and retrieve results.
• OIDC federation: connect your application's identities to Swirls.
• Embed agent chat: add conversations with a Swirls agent to your own web app.
• Hosted Apps: use a Swirls-hosted interface when it fits your application.