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, validate a candidate schema, 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.

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://entities/{entity}/{id} — a single record.

Read tools — list_records, get_record, list_schemas, get_schema, list_jobs_by_state, get_job, read_event_log, list_notifications.

Write tools (guarded) — create_record, update_record, transition_job (fire an FSM event), upsert_schema (author a new schema version), and delete_record (opt-in).

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 writes a new schema version; it never edits history, and the event log is never rewritten.
• 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.

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

Some surfaces are planned but not in the current server: form submission, guided app scaffolding, MCP prompts, 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.