MCP server

The FastYoke MCP server (@fastyoke/mcp) exposes a tenant to any Model Context Protocol host — Claude Desktop, Claude Code, or any other MCP client — so an AI assistant can read your data and drive your workflows through a standard interface.

It is a thin, token-authenticated client of the same REST API the SDK uses: no new backend, nothing copied anywhere, and everything scoped to the API token you hand it. Business rules, multi-tenancy, and FSM guards all stay on the server — the MCP server only speaks the protocol on one side and the tenant API on the other.

What it exposes

Two surfaces, in one server:

• Operate (runtime) — query entity records, read the append-only event log, list FSM jobs by state, fire transitions, and read notifications.
• Build (design-time) — introspect entity schemas and FSM definitions, read a workflow as a stage list, validate a candidate schema or a stage-list proposal, and author a new schema version.

Reads are available whenever the token permits them. Writes are guarded (see below) and can be turned off entirely for a read-only deployment.

Install and configure

The server runs locally over stdio and is launched by your MCP host — there is nothing to install ahead of time. Point it at your tenant with an API token by adding it to the host's MCP configuration:

{
  "mcpServers": {
    "fastyoke": {
      "command": "npx",
      "args": ["-y", "@fastyoke/mcp"],
      "env": {
        "FASTYOKE_BASE_URL": "https://app.fastyoke.io",
        "FASTYOKE_PAT": "fy_pat_…",
        "FASTYOKE_TENANT_ID": "ten_…"
      }
    }
  }
}

Mint the token from API tokens and give it only the scopes the assistant needs — the token is the whole security boundary, and a narrower token is the simplest way to limit what the assistant can do. The server sends it only as a bearer credential to your FASTYOKE_BASE_URL; it is never written to a log or returned in a tool result.

The token's scopes also shape what the assistant sees. On startup the server reads the token's grant and registers only the tools it covers, so a data:read token advertises record reads and nothing else — the assistant never proposes an action it would be refused. Grant workflow:read to add the schema and job surface, workflow:execute to start jobs and fire transitions, workflow:admin to author schemas, data:write for record mutations, or admin:* for all of it.

Environment variables

Tools and resources

Resources — stable, referenceable reads the host can cache:

• fastyoke://schemas — the tenant's entity schemas.
• fastyoke://schemas/{id} — one schema, including its FSM states and transitions.
• fastyoke://workflows/{id}/stages — the same workflow as the stage list draws it: the start stage, the main path and side paths, and each action with the words a person sees, where it goes, its condition, and its follow-up steps. This is a view. The schema resource stays the stored document.
• fastyoke://entities/{entity}/{id} — a single record.

Read tools — list_entity_kinds (what entity kinds exist — the discovery call the others build on), list_records (search, sort, and multi-condition filters), get_record, list_schemas, get_schema, list_jobs_by_state, get_job, read_event_log, list_notifications.

Write tools (guarded) — create_record, update_record, create_job (start a workflow), transition_job (fire an FSM event), upsert_schema (author a new schema version), propose_workflow (propose a stage-list change; dry run by default, and a real apply appends one schema version), yoke_apply (install or update an app from its Yoke source), and delete_record (opt-in).

Prompt — workflow_stage_list tells the host to read fastyoke://workflows/{id}/stages, to speak in stage, action, goes to, condition, and follow-up, and to submit the proposal document. It does not grant a tool. A condition in that document is rows (a field, an operator, and a value), not a sentence.

Yoke language tools — an assistant can author a whole app as source rather than as JSON: yoke_compile turns a .yoke source into the document a tenant installs (or reports every error with its position), yoke_decompile turns a document — including one exported from a tenant — back into canonical source, and yoke_lint runs the ruleset over a source under a profile (tenant by default).

The same server can build an app from named, checked steps instead of writing raw source. yoke_patterns lists the patterns (a record with its pages, a workflow, an owner, line items, an audit trail, approval, a ledger and balance, evidence before an event, conversion, due dates, a dashboard, reference data, demo rows) and yoke_pattern_apply applies one: the result always compiles, and every line the pattern does not touch is left as it was. yoke_complete applies the ruleset's mechanical fixes and lists the ones that need a decision. yoke_templates and yoke_template_build build a whole starter app from a template or from answers to a short questionnaire. None of these installs anything; they return a new source.

All of these run inside the server and touch no tenant, so every credential gets them, read-only servers included. yoke_apply is the write: it compiles, lints under the tenant profile and, only with dry_run: false, installs the app — creating it for a new slug or updating an installed one, with the source stored beside the document so the Studio's code tab reopens it. Ruleset errors stop an install unless force: true.

Guarded writes and safety

The server is deliberately conservative about changing a live tenant:

• Dry run on every mutation. Each write tool accepts a dry_run flag. With it set, the tool validates the request and reports what would happen — the resulting state, or the validation errors — without committing anything.
• The FSM stays authoritative. A real transition_job is evaluated by the server-side FSM guards; the assistant cannot fire a transition the workflow doesn't allow.
• Append-only stays append-only. upsert_schema and propose_workflow each write a new schema version; neither edits history, and the event log is never rewritten. propose_workflow refuses a proposal whose base_version is no longer the active one, and it refuses a deletion or an event rename until the matching confirm flag is set. yoke_apply goes through the same install path the Studio uses: every install appends a revision to the app's history.
• Source first. yoke_apply defaults to a dry run: the assistant sees the slug, the findings and what would happen, and nothing is sent until it says dry_run: false.
• The admin cancel override is not exposed. Forcing a job to a terminal state, bypassing guard evaluation, remains an operator action in the web portal — it is intentionally absent from the MCP surface so an assistant can't defeat the workflow.
• Deletes are opt-in and confirmed. delete_record only appears when FASTYOKE_MCP_ALLOW_DELETE=1, and every call requires an explicit confirmation flag.
• Read-only mode. With FASTYOKE_MCP_READONLY=1, no write tool is registered at all — the assistant can observe and reason about your operation but cannot change it. The flag is the outer gate: a read-only server exposes no write tool even for an admin:* token.
• The tool list matches the token. Tools whose scope the token lacks are never advertised. This is for the assistant's benefit, not security: scopes are enforced on every request server-side either way, so an assistant that ignored the tool list would still be refused.

Everything the server does is tenant-scoped by the token, exactly as described in tenant scoping; the MCP layer adds no ambient credentials of its own.

Not yet included

Making an app from a saved workflow is offered in the workflow designer for tenants with Studio. An assistant still installs source with yoke_apply; there is no separate install tool.

Some surfaces are planned but not in the current server: form submission, further prompts beyond workflow_stage_list, and a remote FastYoke-hosted endpoint (today the server runs locally). Until those land, use the SDK or CLI for those flows.

Related

• API tokens — mint and scope the fy_pat_… token the server authenticates with.
• Tenant scoping — how every request is isolated to your tenant.
• SDK — the typed client the MCP server is built on, for when you're writing code rather than driving the tenant from an assistant.