---
title: MCP server
summary: Connect an AI assistant — Claude Desktop, Claude Code, or any Model Context Protocol host — to a FastYoke tenant with the @fastyoke/mcp server. Query records, drive FSM jobs, and author schemas, all token-scoped with guarded writes.
order: 7
---

# MCP server

The FastYoke MCP server (`@fastyoke/mcp`) exposes a tenant to any
[Model Context Protocol](https://modelcontextprotocol.io) 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](/docs/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:

```json
{
  "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](/docs/auth/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

| Variable | Required | Purpose |
| --- | :---: | --- |
| `FASTYOKE_BASE_URL` | yes | Your API origin, e.g. `https://app.fastyoke.io`. |
| `FASTYOKE_PAT` | yes | A tenant API token (`fy_pat_…`). |
| `FASTYOKE_TENANT_ID` | yes | The tenant the token belongs to; the server refuses to start on a mismatch. |
| `FASTYOKE_MCP_READONLY` | no | Set to `1` to register only read tools and resources — no mutations at all. |
| `FASTYOKE_MCP_ALLOW_DELETE` | no | Set to `1` to expose the opt-in `delete_record` tool (off by default). |

## 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](/docs/jobs); 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](/docs/developers/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](/docs/sdk) or [CLI](/docs/cli) for those flows.

## Related

- [API tokens](/docs/auth/api-tokens) — mint and scope the `fy_pat_…`
  token the server authenticates with.
- [Tenant scoping](/docs/developers/tenant-scoping) — how every request
  is isolated to your tenant.
- [SDK](/docs/sdk) — the typed client the MCP server is built on, for
  when you're writing code rather than driving the tenant from an
  assistant.