MCP server

Get a contact

One contact with their email, phone number and the jobs they are on.

Scopes: contacts:read

Calls: GET /v1/contacts/{contact_id}

{
  "contact_id": "b2d4e6f8-1a3c-5e7b-9d0f-2a4c6e8b0d1f"
}

Get an estimate

One estimate with its totals, deposit, dates, notes and terms; with include_lines, its sections and lines.

Scopes: estimates:read

Calls: GET /v1/estimates/{estimate_id}

{
  "estimate_id": "9e8d7c6b-5a49-4382-a1b0-c9d8e7f6a5b4",
  "include_lines": true
}

Get an invoice

One invoice with its total, amount due, balance and payment link; with include_lines, its sections and lines.

Scopes: invoices:read

Calls: GET /v1/invoices/{invoice_id}

{
  "invoice_id": "1a2b3c4d-5e6f-4708-9192-a3b4c5d6e7f8"
}

Get a job

One job with its contacts (with their ids, emails and phone numbers) and custom field values.

Scopes: jobs:read

Calls: GET /v1/jobs/{job_id}

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d"
}

Schedule for a week

Everything booked or due in the seven days from week_start: calendar events, work orders due, and (when a job is given) that job's open tasks due. It makes several calls to WoodSystems (one for events, one or more pages of work orders, and pages of tasks), and each counts toward the account's API usage, so prefer it over calling the pieces separately. Work orders are read newest first; if there are more than it reads, the answer says the list is incomplete.

Scopes: calendar:read, work_orders:read, tasks:read

Calls: GET /v1/calendar/events, GET /v1/work-orders, GET /v1/jobs/{job_id}/tasks

{
  "week_start": "2026-10-05T00:00:00-05:00"
}

Get a work order

One work order with its steps in order and the step it is at now.

Scopes: work_orders:read

Calls: GET /v1/work-orders/{work_order_id}

{
  "work_order_id": "4b5c6d7e-8f90-4a1b-2c3d-4e5f60718293"
}

List calendar events

Calendar events that overlap a window, earliest first: installs, site measures, deliveries, meetings, with the job, departments and people on each. A production user sees their own and their departments' events.

Scopes: calendar:read

Calls: GET /v1/calendar/events

{
  "start": "2026-10-05T00:00:00-05:00",
  "end": "2026-10-12T00:00:00-05:00"
}

List custom job fields

The custom fields the account keeps on jobs: id, label, type and the allowed options for list fields. Use the ids as field_id in create_lead's custom_fields.

No inputs.

Scopes: meta:read

Calls: GET /v1/meta/custom-fields

{}

List estimates

Estimates newest first, with number, name, job, status, subtotal, tax and total. Needs an office role or above.

Scopes: estimates:read

Calls: GET /v1/estimates

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d"
}

List invoices

Invoices newest first, with number, job, status, total, amount due and balance. Needs an office role or above.

Scopes: invoices:read

Calls: GET /v1/invoices

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d"
}

List job statuses

The account's job pipeline: main statuses in order, and the phases under each (a phase names its parent). Use an id from here as status_id for search_jobs or update_job_status. Accounts name their own statuses, so look them up rather than assuming.

No inputs.

Scopes: meta:read

Calls: GET /v1/meta/job-statuses

{}

List purchase orders

Purchase orders newest first, with number, supplier, job, status, expected delivery and totals.

Scopes: purchasing:read

Calls: GET /v1/purchase-orders

{
  "status": [
    "submitted",
    "partial"
  ]
}

List a job's tasks

A job's tasks, newest first, with who they are assigned to, due date and status. WoodSystems lists tasks per job; there is no account-wide task list on this connection.

Scopes: tasks:read

Calls: GET /v1/jobs/{job_id}/tasks

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d",
  "completed": false
}

List the team

The account's active people with their role and whether they can be a project manager. Use their ids to assign tasks or to filter calendar events. Email addresses are not included.

No inputs.

Scopes: meta:read

Calls: GET /v1/meta/users

{}

List work orders

Work orders newest first, with number, job, type, current step, due date, priority, progress and who is assigned. Readable from a production role up.

Scopes: work_orders:read

Calls: GET /v1/work-orders

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d"
}

Search contacts

Find people in the account's address book (customers, contractors and anyone put on a job), newest first. Use get_contact for the jobs a person is on.

Scopes: contacts:read

Calls: GET /v1/contacts

{
  "query": "Whitfield"
}

Search jobs

Find jobs (leads, opportunities and jobs), newest first. Returns each job's id, number, name, stage, status, address, dates, project manager and value. Use get_job for its contacts and custom fields.

Scopes: jobs:read

Calls: GET /v1/jobs

{
  "query": "Whitfield",
  "stage": "job"
}

Search products

Find products in the account's catalog, newest first, with kind (made, purchased or service), unit, price and cost. Prices and costs are blank for a role that cannot see them.

Scopes: products:read

Calls: GET /v1/products

{
  "query": "shaker door"
}

Search suppliers

Find the account's suppliers, newest first, with contacts, lead time and payment terms. Use the id as vendor_id for create_purchase_order.

Scopes: purchasing:read

Calls: GET /v1/vendors

{
  "query": "Rugby"
}

Who am I connected as

Call this first, before any other WoodSystems tool. Returns the account, the user every call acts as, their role (owner, admin, manager, office or production), the permissions this connection holds, the environment (live or sandbox), and what this connection can never do. Respect the role: WoodSystems refuses what the role cannot do, and a production user's money fields come back blank, so say the amounts are not visible to them instead of inventing numbers.

No inputs.

Scopes: meta:read

Calls: GET /v1/account

{}

Add a note to a job

Post a note on a job's messages, written as the acting user. Everyone following the job is notified, and the note cannot be edited or deleted through this connection. To mention someone write @[user_id:Name] with an id from list_team.

Scopes: notes:write

Calls: POST /v1/jobs/{job_id}/notes

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d",
  "content": "Customer confirmed the walnut finish by phone."
}

Complete a task

Mark a task done. It moves to the account's Complete status; someone can reopen it in the app.

Scopes: tasks:write

Calls: POST /v1/tasks/{task_id}/complete

{
  "task_id": "7c8d9e0f-1a2b-3c4d-5e6f-708192a3b4c5"
}

Book a calendar event

Book an event on the account's calendar for a job (or an internal or external event). The people in its departments and teams are notified, as in the app.

Scopes: calendar:write

Calls: POST /v1/calendar/events

{
  "title": "Site measure",
  "start": "2026-10-08T09:00:00-05:00",
  "end": "2026-10-08T10:00:00-05:00",
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d"
}

Create a lead

Put a new lead in the account's pipeline. The office sees it at once and is notified, the same as a lead from the website form. Give at least an email or a phone number so someone can follow up. Calling twice with the same details within a minute makes one lead, not two.

Scopes: jobs:write

Calls: POST /v1/leads/create

{
  "name": "Whitfield kitchen remodel",
  "first_name": "Dana",
  "last_name": "Whitfield",
  "email": "dana@example.com",
  "notes": "Wants walnut uppers, install before March."
}

Draft a purchase order

Create a DRAFT purchase order with its lines, for a job or (without job_id) for stock. Nothing goes to the supplier: someone reviews and submits it in the app. Every line is checked first, so one bad line refuses the whole order. Needs a manager role or above.

Scopes: purchasing:write

Calls: POST /v1/purchase-orders

{
  "name": "Hardware for Whitfield kitchen",
  "vendor_id": "6d7e8f90-a1b2-4c3d-8e4f-5a6b7c8d9e0f",
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d",
  "lines": [
    {
      "item_name": "Soft close hinge",
      "quantity": 24,
      "unit_cost": 4.5
    }
  ]
}

Create a task

Create a task on a job and assign it. The people assigned are notified, as for a task made in the app. Ask who it is for if the user has not said; a task is never assigned to anyone by default.

Scopes: tasks:write

Calls: POST /v1/jobs/{job_id}/tasks

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d",
  "title": "Order hinges",
  "due_date": "2026-10-09",
  "assignee_ids": [
    "5a1e2b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
  ]
}

Email contacts on a job

Email contacts on a job from the acting user's own connected mailbox. It becomes a thread on the job's messages and replies come back to it. A sent email cannot be taken back, so without confirm=true this only returns a preview (recipients, subject, body); show it to the user and call again with confirm=true once they agree. If the acting user has not connected a mailbox in WoodSystems the send is refused and nothing is sent.

Scopes: jobs:read, comms:send

Calls: GET /v1/jobs/{job_id}, POST /v1/jobs/{job_id}/emails

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d",
  "contact_ids": [
    "b2d4e6f8-1a3c-5e7b-9d0f-2a4c6e8b0d1f"
  ],
  "subject": "Install date",
  "body": "Hi Dana, we are booked to install on the 14th. Does that still suit?"
}

Change a job's status

Move a job to another status or phase, by the same rules as the app (a job with estimates cannot go back to Lead; closing needs its invoices settled). Moving a job to Closed or Lost, or a phase under them, is final for the office: without confirm=true it only returns a preview of the change; show it to the user and call again with confirm=true once they agree. Marking a job lost needs a manager role.

Scopes: meta:read, jobs:read, jobs:write

Calls: GET /v1/meta/job-statuses, GET /v1/jobs/{job_id}, POST /v1/jobs/{job_id}/status, POST /v1/jobs/{job_id}/move-to-lost

{
  "job_id": "3f9a1c77-5e3b-4a02-9d8e-2c7b6a1f0e4d",
  "status_id": "0b6c2d1e-7f3a-4c58-9e21-5d4b3a2f1c0e"
}

woodsystems://account

Account

The account, the user this connection acts as, their role and the permissions it holds.

Scopes: meta:read

Calls: GET /v1/account Kept for 5 minutes.

woodsystems://custom-fields

Custom job fields

The custom fields the account keeps on jobs, with their types and options.

Scopes: meta:read

Calls: GET /v1/meta/custom-fields Kept for 5 minutes.

woodsystems://statuses

Job statuses

The account's job pipeline: main statuses in order and the phases under them.

Scopes: meta:read

Calls: GET /v1/meta/job-statuses Kept for 5 minutes.

woodsystems://team

Team

The account's active people and their roles.

Scopes: meta:read

Calls: GET /v1/meta/users Kept for 5 minutes.

daily_briefing

Daily briefing

A start-of-day briefing: who you are acting as, this week's schedule, and jobs that need attention.

Arguments: focus (optional)