Run your first Blueprint in Diaphora cloud

The Frags runtime executes blueprints wherever it runs — on your own machine or on Diaphora's managed infrastructure. This guide takes the shortest path to a real, cloud-hosted run: connect your tools, write a Blueprint that uses them, deploy it, and call/schedule it.

Before you start

You'll need a Diaphora workspace. If you don't have one yet, sign up at diaphora.ai - a workspace is created for you on sign-up.

Everything in this guide is done from the Diaphora dashboard. If you want to prototype blueprints on your own machine first, see Running Frags Locally.

Step 1: Connect your tools

A Blueprint that calls real tools — Slack, Salesforce, Notion, a database — needs those tools connected before it runs. In Diaphora cloud, tool connections are workspace-level: you connect a tool once and every Blueprint that declares require mcp <name> can use it.

Open Tools in your workspace. For each MCP server you want to use:

Click + Add MCP Servers.
Name the MCP server.
Paste the server's URL.
If the server requires OAuth, supply the client_id and client_secret from that tool and click Authorize — Diaphora walks you through the OAuth flow and stores the resulting tokens. Please note, best practice is to add all secret values to our vault here.
Wait for the status to show ready. A tool that shows an error won't be callable from a blueprint.

Built-in tools — web search (use search) and HTTP (use http) are available in every workspace without any configuration.

For how tool connections work under the hood, see Setting up tools.

Step 2: Write your blueprint

A Blueprint is an FML file that declares the tools it needs, the inputs it accepts, and the sessions that do the work — each with a typed output schema. Here's a complete example: it fetches CRM and Slack signals ahead of a meeting, then builds a structured prep doc.

Start with the assistant. In app.diaphora.ai, describe a small workflow in the assistant panel and review the FML it drafts. Start with the hello-world example to see an input become a structured result before connecting external services.

FML

require mcp salesforce
require mcp slack

parameter("meetingQuery", type=string, title="Meeting or contact to prep for")

session("fetch-signals") {
    use mcp salesforce
    use mcp slack

    + Pull the most recent Salesforce account activity and Slack messages
      related to {{ .params.meetingQuery }}.
    - Extract what's most relevant to the upcoming call.

    schema {
        account_name: string
        recent_activity: string[]   # Key Salesforce events from the last 30 days
        slack_signals: string[]     # Relevant messages or threads
    }
}

session("build-prep", after="fetch-signals") {
    context true
    - Build a structured call prep document from the signals.

    schema {
        overview: string
        talking_points: string[]
        open_items: string[]
        suggested_agenda: string[]
    }
}

Four things are the work:

require mcp salesforce / require mcp slack — declares the tools this Blueprint uses. These must be connected (Step 1) before the Blueprint can run.
parameter(...) — a typed, validated input the caller supplies at run time. Reference it anywhere with {{ .params.meetingQuery }}.
session("fetch-signals") { ... } — the first isolated LLM step. The + prePrompt gathers live data (tools are available here); the - prompt turns what was gathered into typed output.
session("build-prep", after="fetch-signals") { ... } — waits for fetch-signals to finish, pulls its output into context with context true, and builds the prep doc.

For the full session anatomy, see Anatomy of a session. For how data moves between sessions, see Data flow: params, vars & context.

Step 3: Save and review the workflow

Save the workflow in the plan editor. A plan in the app is the workflow described by your Blueprint source file. Before running it, review:

Tools — each require mcp <name> should refer to a connection you have set up and authorized.
Parameters — check required inputs, types, and defaults.
Source — confirm that each session declares the tools it should use and the output it should return.

If saving or running fails, inspect the reported error and correct the source, inputs, or tool connection it identifies. Saving a plan does not by itself verify that it can execute successfully.

Step 4: Run it

There are three ways to run a Blueprint.

From the dashboard. Open the Blueprint and click Run Plan. Fill in the parameters and click Run Plan. The execution panel streams each session's output as it finishes; when the run completes, you get the full typed JSON result keyed by session name.

Over the API. Call the stored-plan run endpoint with your Blueprint ID (planId) and pass its inputs inside parameters:

Shell

curl -X POST "https://api.diaphora.ai/router/plan/<planId>/_run" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"meetingQuery": "Acme Corp renewal call"}}'

See the API reference for streaming runs and long-running execution patterns.

From an MCP client. Connect to https://mcp.diaphora.ai/mcp using OAuth with a pre-registered client. This uses a separate setup from the API bearer token: register your client's callback URI and configure the client credentials it supports. The MCP tools let you find, inspect, and run existing plans and retrieve their results; they do not provide plan editing or schedule management. Follow the MCP reference for setup, then verify a tool call—not just a successful login.

Step 5: Schedule it (optional)

Open Schedules in the left rail of the Blueprint overview, click + New schedule, and set:

Cadence — Hourly, Daily, Weekly, or Monthly.
Timezone — the platform handles daylight-saving shifts.
Parameters — the values each scheduled run uses, frozen at schedule creation. Edit the schedule to change them without redeploying the Blueprint.

The platform shows a plain-English preview as you configure — Every Monday at 9:00 AM (America/New_York) — so there's no cron syntax to verify. For a full walkthrough including a real weekly email brief, see Schedule recurring blueprints.

What you have now

A single FML file, deployed to Diaphora cloud, gives you:

A stable API endpoint callable from any HTTP client or your app's backend.
Access through MCP tools from a client compatible with the documented transport and OAuth setup.
Persistent tool connections — auth managed by the platform, not baked into the Blueprint.
An optional schedule with its own saved parameters and connections that must work without interactive authentication.

The Blueprint itself stays portable: the same FML runs locally with the Frags CLI or on Diaphora cloud — only the tool connection layer changes.

Next steps

Browse ready-made blueprints in the Blueprint marketplace — pick one, connect its tools, and deploy.
Go deeper on sessions in Anatomy of a session.
Connect more data sources in Connect Frags to your data.
Fan out sessions and add conditional logic in Control the flow of a blueprint.
Call a deployed Blueprint from your application with the Python or TypeScript SDK.

← All guides

Connect your tools, write a blueprint, deploy it, and call it — the shortest path to a real, cloud-hosted run with a stable API endpoint, MCP tool, and optional schedule.