Platform

Lightworks MCP

Lightworks MCP (Model Context Protocol) server lets AI agents — Claude, ChatGPT, Cursor, VS Code, and any other MCP-compatible client — read and edit your QMS records on your behalf. The server speaks the same record, database, and PR model as the REST API, so writes still flow through a pull request for human review and signature.

Endpoint

https://app.lightworks.md/api/mcp

Authentication

Supported clients authenticate automatically via OAuth or API Token. Open Settings → Lightworks MCP and click Connect next to your client.

For clients not listed, you can authenticate with a Lightworks API token:

Authorization: Bearer YOUR_TOKEN

Generate one from Settings → API Tokens:

Read tokens (read:databases) work on every plan
Write tokens (read:databases + write:databases) require the paid plan

Tokens can be revoked or reactivated at any time. The workspace's LIGHTWORKS_ORG_ID is shown at the bottom of the API Tokens tab.

Supported clients

Client	Auth
Claude (Desktop, Web & Code)	OAuth
ChatGPT	OAuth
Cursor	OAuth
VS Code	OAuth
Any other MCP client	Bearer token

Connecting a client

Open Settings → Lightworks MCP and click Connect next to your client. You'll be redirected through OAuth and returned to the settings panel automatically.

For clients not listed, see the bearer token instructions above and refer to your client's MCP documentation for the config format.

Available tools

Discovery (read)

Tool	Description
`list_databases`	List QMS databases visible in the connected repo. Returns `id`, `name`, and `parent` for each. Paginated.
`get_database`	Fetch a single database by its path. Returns `name`, `parent`, and the full property schema. Example id: `"reqs"` or `"parent-db/child-db"`.
`list_records`	List records directly under a database. Sub-database records are not included; query their database separately. Paginated.
`get_record`	Fetch a single record by id. Returns its properties and markdown body. Example: `{ db: "reqs", id: "REQ-12" }`.

Records (write)

Tool	Description
`create_record`	Create a new record on a PR branch. Not idempotent — every call mints a new record id. Requires an open PR from `create_pr` and a properties object that satisfies the database schema.
`update_record`	Update an existing record on a PR branch by merging the provided properties into its frontmatter. Idempotent — repeating the same call results in the same final state.
`delete_record`	Delete a record on a PR branch. Idempotent — deleting a record that no longer exists returns `404` without side effects.

Pull requests (write)

Tool	Description
`create_pr`	Create a Lightworks API PR branch. Returns a `prId` you pass to `create_record` / `update_record` / `delete_record`, then `finalize_pr`. Idempotent only when `originatorContext.pr_number` is provided (deterministic prId `pr-{prNumber}`); without it each call mints a fresh random prId.
`cancel_pr`	Cancel an API PR: close any open GitHub PR and delete the branch. Idempotent — calling on an already-cancelled PR succeeds silently.
`finalize_pr`	Open a GitHub pull request for the API PR branch. Idempotent — returns the existing PR if one is already open.

Typical flow

Writes are grouped into a PR so a human can review and sign before anything lands on the default branch.

create_pr → get a prId and branch
create_record / update_record / delete_record — each call commits to the branch
finalize_pr → opens a GitHub pull request in your QMS repo for review and signature
cancel_pr if you change your mind → closes the branch without merging

For one-off reads, you can call the discovery tools directly — no PR required.

Developers — the underlying REST API and GitHub Actions workflow
Settings — generate API tokens and find your LIGHTWORKS_ORG_ID
Pull Requests — review, comment, and merge changes opened by an agent