BackCrew FieldRoutes Server

Think of this like a brand-new employee on their first day, not a business partner. A new hire only does the exact tasks you've shown them, nothing more, until you decide they're ready for more responsibility.

It lets you connect an AI assistant like Claude or ChatGPT to your FieldRoutes (formerly PestRoutes) account, so you can ask for things in plain English, like "find this customer," "what's on the route Tuesday," or "is this invoice paid," instead of clicking through the FieldRoutes website yourself. On day one, it only knows how to look things up. You decide if and when to train it up to doing more.

Built by BackCrew, part of a series of free tools like this for the software pest control companies use every day.

Not a developer? That's fine. Everything up through "Testing it safely" is written for you, no coding background needed.

---

Contents

• What this actually does
• Why use an independent MCP server instead of the platform's own AI?
• A quick note on FieldRoutes' terminology
• Also from BackCrew
• Some words you'll see, explained
• How this keeps you safe by default
• What it can look up (always safe)
• ⚠️ What it can change (off by default)
• How to set it up
• Connecting it to Claude
• Things you can try asking
• Testing it safely
• For developers
• What's next
• Built by BackCrew
• License

What this actually does

Let's be upfront about what this is, because it's easy to oversell: this is not an all-knowing office assistant that understands your business and handles things for you. It's a specific, listed set of actions, like "look up a customer," "schedule an appointment," or "create an invoice," that an AI assistant like Claude or ChatGPT is allowed to trigger when you ask for them in plain English. The AI doesn't have judgment about your business; it matches what you ask for to the closest action on its list and does exactly that, nothing more.

That's still genuinely useful. Instead of this:

Open FieldRoutes → search customers → click into the record → find the right tab → scroll to find this week's appointments...

You can just say:

"Find the customer named Dana Ruiz and show me any appointments scheduled for her this week."

And the assistant does the clicking for you, using the same actions you'd take yourself, just faster, and in plain English.

Why use an independent MCP server instead of the platform's own AI?

Software platforms are increasingly shipping their own built-in AI features. Worth knowing why you might still reach for this instead:

• No plan-tier gates. Native AI features are often locked to a platform's most expensive plan. This project just needs API access, which is usually available on lower tiers too.
• Cross-platform, not walled off. A platform's own AI only sees that platform's own data; it has no reason to work fluently with your accounting software, another CRM, or your email, since those are somebody else's product. An MCP-connected assistant can have multiple servers attached at once (this one plus another BackCrew server covering a different part of your business), so it can work across your whole stack in one conversation.
• Your choice of AI, not theirs. You keep using whichever assistant you already trust (Claude, ChatGPT, whatever) instead of learning a new vendor-specific AI interface.

A quick note on FieldRoutes' terminology

FieldRoutes uses a few names that don't match what you might expect from other software:

• A "ticket" is an invoice, the bill for work done.
• A "subscription" is a recurring service plan for a customer: the ongoing quarterly/monthly treatment agreement, not a one-off job.
• An "appointment" is a single scheduled visit, which may or may not be tied to a subscription.

The tool names in this project follow FieldRoutes' own terms so they line up with what you'll see in the FieldRoutes app itself.

Also from BackCrew

This is one of several MCP connectors BackCrew builds, same idea, different software. We've also got QuickBooks for the accounting side, plus CRM connectors like HubSpot and GoHighLevel for lead and marketing data. Full list and what's live right now: see ROADMAP.md.

Beyond this repo: once a business gets comfortable with an AI assistant reading its data, there's often more it wants to do with it, like catching missed calls faster, processing invoices and paperwork automatically, following up on quotes without someone having to remember, reactivating customers who've gone quiet, or pulling reports without digging through the software. That's a separate, scoped conversation, not part of this free, open-source repo. Same contact as in Built by BackCrew below if it's something you want to explore.

Some words you'll see, explained

• API, short for "Application Programming Interface," is a locked door into FieldRoutes' data that only software (not a person clicking a mouse) can open. This project is a key that opens that door, so an AI can read and update your data directly instead of needing a screen to click through.
• MCP, short for "Model Context Protocol," is the standard way an AI assistant like Claude or ChatGPT is told "here's exactly what you're allowed to do, and how to do it." This project speaks that standard, which is why it plugs into Claude (and similar tools) with no custom setup.
• Server is a small program that sits between Claude (or ChatGPT) and FieldRoutes, translating requests back and forth. You start it once and leave it running; you never interact with it directly.
• Repo (short for "repository") is the folder of code for this whole project. "Clone the repo" just means "download a copy of this project."
• Authentication key / token are two long, private password-like codes that prove a request is really coming from you. FieldRoutes issues these to your account directly (steps below); you never share them.
• Terminal is a plain-text window where you type commands instead of clicking buttons. Setup involves a few terminal commands, listed step-by-step below.
• Tool is one specific action the AI is allowed to take, like "look up a customer" or "create an invoice." Each one is listed and named individually; there's no hidden catch-all action.

How this keeps you safe by default

The new-hire idea from the top is the real architecture, not just a nice way of putting it:

• Out of the box, this server can only look things up. It ships in read-only mode, meaning nothing it does can create, change, delete, or charge anything in your FieldRoutes account, because those actions aren't even switched on.
• When you're ready for more, you choose a responsibility level, not an all-or-nothing switch. Turning on write access (FR_MCP_MODE=read_write, see setup) still requires picking a profile that caps what's allowed:
  • readonly-owner: same as the default. Look-ups only.
  • office-ops: everyday front-desk and dispatch work, like booking an appointment, updating a customer, creating an invoice, or building a route. No deletes, no employee-record changes, no payment/card handling. Those stay off even in this mode.
  • admin: everything, including deletes, employee record management, and anything touching payments or stored card/ACH details.
• A typo can't accidentally hand out more trust than you intended. If the profile setting is ever misspelled or invalid, the server falls back to the safest option (read-only) rather than the most permissive one.

What it can look up (always safe)

These actions only read data; nothing here can change a record or cost you anything to run. This is what's available in the default setup, with no extra steps:

What it covers	Examples of what it can look up
Customers	Search and view customer profiles
Appointments	View scheduled visits and their status
Invoices (tickets)	View invoices and their line items
Recurring service plans (subscriptions)	View a customer's ongoing service agreement
Employees	View technicians, sales reps, and office staff
Notes	View notes on a customer
Routes	View technician routes for a date
Payments	View payment history (payment method details are masked)
Regions, offices, service types, cancellation reasons	View how your account is configured
Chemical/product records	View what was applied on an appointment (compliance/reporting)
Documents	View files attached to a customer
Flags & tasks	View labels and to-dos assigned to records

39 look-up actions in total.

⚠️ What it can change (off by default)

Everything below this line can create, edit, or delete something real in your FieldRoutes account. None of it is available until you deliberately turn it on (see How this keeps you safe by default). This section exists so you know exactly what you'd be turning on, not because it's active right now.

office-ops level (everyday front-desk and dispatch actions):

What it covers	Examples of what it can do
Customers	Add or update a customer
Appointments	Schedule, reschedule, cancel, or mark an appointment complete
Invoices (tickets)	Create an invoice, add/edit line items
Recurring service plans (subscriptions)	Set up or update a customer's recurring service
Notes	Add or update a note
Routes	Build or update a technician route
Documents	Upload or update a document
Flags & tasks	Assign a flag, create or update a task

admin level only (hard to reverse, financially sensitive, or HR-facing, kept separate from everyday office work on purpose):

• Deleting an invoice, invoice line item, note, document, or flag assignment
• Creating or updating employee records (kept separate from front-desk work since it touches HR/access data)
• Anything involving payments or stored card/ACH details: recording a payment (which can trigger a real charge), issuing a refund, or creating/updating/deleting a stored payment method. This entire area stays admin-only, including just viewing stored payment profiles (office-ops can view basic payment history, but not the stored card/ACH profiles themselves)

How to set it up

No context-switching here: do these three steps in order, and you won't need to jump back and forth.

You'll need a computer with Node.js installed (free software this project runs on) before you start.

Step 1: Make a folder for this on your computer

Open Finder (Mac) or File Explorer (Windows), go to your Desktop or Documents, and create a new folder. Give it a name you'll recognize later, like backcrew-mcp-fieldroutes.

That's it for now. Just know where this folder is. Everything else gets put inside it.

Step 2: Get your FieldRoutes credentials

Unlike some platforms, FieldRoutes doesn't have a self-service "generate a key" button; you'll need to request access directly. Do this now, before touching the terminal:

1. Contact your FieldRoutes account rep or FieldRoutes support and ask for API access
2. They'll give you three things: your subdomain (the company-name part of your FieldRoutes login URL), an authentication key, and an authentication token
3. Copy all three into a temporary note somewhere; you'll paste them in during Step 3

Reference docs: fieldroutes.dev/documentation.

Step 3: Install it

With your folder made and your credentials in hand, this is one continuous run: don't skip ahead or double back.

1. Open a terminal. On a Mac, press Cmd+Space, type "Terminal," and hit enter. On Windows, click the Start menu, type "PowerShell," and hit enter. Use PowerShell rather than Command Prompt: a couple of the commands below, like pwd, only work in PowerShell.
2. Type cd (with a space after it), then drag your Step 1 folder from Finder/File Explorer straight into the terminal window, and it'll paste the folder's path in automatically. Press enter.
3. Paste this exact command and press enter. It downloads the project directly into the folder you made (the trailing . matters, it means "put it here, not in a new folder"):

   git clone https://github.com/jayson-svg/backcrew-mcp-fieldroutes.git .
   

4. Paste this and press enter. It installs the project's dependencies:

   npm install
   

5. Paste this and press enter. It builds the project:

   npm run build
   

6. Paste this and press enter. It prints the full folder path. Don't close this terminal window yet; you'll need this exact text in the next section.

   pwd
   

7. Paste this and press enter. It creates your settings file from a template:

   cp .env.example .env
   

8. Open that new .env file in a text editor. On a Mac, paste open -e .env into the terminal and press enter. On Windows, paste notepad .env and press enter.
9. Find the lines that say FIELDROUTES_SUBDOMAIN=, FIELDROUTES_AUTH_KEY=, and FIELDROUTES_AUTH_TOKEN=. Paste in the matching values you collected in Step 2, right after each =, with no extra spaces or quotes.
10. Leave FR_MCP_MODE=read_only and FR_MCP_PROFILE=readonly-owner exactly as they are for now. That's the safe default. Save the file and close the editor.

Connecting it to Claude

This step comes last on purpose: it needs the exact folder location from Step 3, and now you have it.

Claude Desktop / Claude Code

Open Claude's settings file (for Claude Desktop, this is claude_desktop_config.json) and add:

{
  "mcpServers": {
    "fieldroutes": {
      "command": "node",
      "args": ["PASTE_YOUR_PWD_OUTPUT_HERE/dist/index.js"],
      "env": {
        "FIELDROUTES_SUBDOMAIN": "your_subdomain_here",
        "FIELDROUTES_AUTH_KEY": "your_key_here",
        "FIELDROUTES_AUTH_TOKEN": "your_token_here",
        "FR_MCP_MODE": "read_only",
        "FR_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

Replace PASTE_YOUR_PWD_OUTPUT_HERE with the exact text the pwd command printed back in Step 3 (keep the /dist/index.js part after it). If you're on Windows, swap any backslashes in that path for forward slashes (for example C:/Users/yourname/Desktop/... instead of C:\Users\yourname\Desktop\...), since the config file needs regular slashes.

Restart Claude. You should see FieldRoutes show up as something Claude can use, with only the look-up actions available, by default.

This also works with ChatGPT and other MCP-compatible AI tools (Cursor, Windsurf, and others); the setup step is basically the same.

Things you can try asking

With the default (read-only) setup:

• "Find the customer named Dana Ruiz"
• "What appointments are on the schedule for tomorrow?"
• "Show me the invoices for this customer"
• "What chemical was applied on the last visit to this address?"

If you later turn on office-ops:

• "Schedule a follow-up appointment for this customer next Tuesday morning"
• "Create an invoice for today's visit"
• "Add a note that the gate code changed"
• "Cancel tomorrow's appointment for this customer since they called to reschedule"

Testing it safely

If and when you decide to turn on write access, a few habits go a long way:

1. Start in read-only mode and stay there for a while. Get a feel for how the AI interprets your requests before you ever let it change anything.
2. When you do turn on office-ops, test on a clearly fake customer first. Create a test customer named something obvious like "ZZZ Test Customer: Do Not Use" and try your first few write actions on that record, not a real one.
3. Never go straight to admin mode. Deletes, employee-record changes, and anything payment-related are hard or impossible to undo, and payments can move real money. office-ops covers real day-to-day work without exposing any of that.
4. Never share your authentication key or token, not in chat, not in a screenshot, not in a support ticket, anywhere. Treat them like a password, because they function like one.
5. If something looks wrong, switch back to FR_MCP_MODE=read_only immediately. That alone guarantees nothing further can be changed, regardless of what profile is set.

For developers

Everything below this point assumes a coding background.

Tool reference

Run the server and call tools/list from any MCP client to see exact input/output schemas: every tool's description includes both the FieldRoutes API operation it maps to and its access tier (e.g. Maps to POST /appointment/create. [tier: office-ops]). Each domain lives in its own file under src/tools/.

The tier/profile system

Every call to registerJsonTool(...) declares a tier: "readonly-owner" | "office-ops" | "admin". At startup, src/toolkit.ts reads FR_MCP_MODE and FR_MCP_PROFILE once, computes the maximum exposed tier, and any tool above that tier is never registered with the MCP server. It doesn't just get hidden from a menu, it's genuinely absent from tools/list and can't be called. FR_MCP_MODE=read_only always wins over FR_MCP_PROFILE regardless of what the profile is set to; only read_write lets the profile setting take effect. An unrecognized profile value falls back to readonly-owner, not the most permissive tier. This is the same pattern used across the rest of this series; see ROADMAP.md for the original writeup.

Project layout

src/
  index.ts          Server entrypoint: registers every tool group and starts stdio transport
  client.ts          Minimal fetch-based FieldRoutes API client (query-string auth, form-encoded body, error handling)
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  tools/
    customers.ts
    appointments.ts
    tickets.ts        (invoices)
    subscriptions.ts  (recurring service plans)
    employees.ts
    notes.ts
    routes.ts
    payments.ts
    reference.ts       (regions, offices, service types, cancellation reasons)
    chemicals.ts
    documents.ts
    flags.ts
    tasks.ts

Notes on the FieldRoutes API

• Base URL: https://{your-subdomain}.pestroutes.com/api/{resource}/{operation} (FieldRoutes was formerly PestRoutes, and the API still runs on the pestroutes.com domain).
• Auth: authenticationKey and authenticationToken as query-string parameters on every request (not headers).
• Most resources follow a search-then-get pattern: {resource}/search takes filters and returns a plain array of matching IDs (no result limit), then {resource}/get takes an array of up to 1000 IDs and returns the full records. This project's search_* and get_* tool pairs mirror that directly rather than hiding it behind a single call, since that's the real shape of the API.
• Search filters support an advanced {"operator": ">", "value": ...} query-object syntax on most date/numeric fields (operators: >, <, >=, <=, =, !=, IN, BETWEEN, LIKE, STARTSWITH, ENDSWITH, CONTAINS). Every search_* tool exposes an extra_filters field for this.
• Full reference: fieldroutes.dev/documentation

This server was built by reading FieldRoutes' public API documentation directly. One caveat worth flagging: the docs page doesn't include a dedicated "Authentication" walkthrough with a worked example. The query-string authenticationKey/authenticationToken pattern and the {subdomain}.pestroutes.com base URL were confirmed from FieldRoutes' own live documentation sandbox URL and corroborating third-party integration docs (Domo's PestRoutes connector), not from an explicit code sample on fieldroutes.dev itself. If your first live call doesn't authenticate, this is the first thing to double-check against what FieldRoutes support gives you.

This repo intentionally stops at honest API access. It does not include business-logic features (like a prioritized collections queue, technician capacity analysis, or automated escalation rules); those live in BackCrew's managed offering, built on top of this open layer, not in this public repo. See ROADMAP.md.

Scope

FieldRoutes' API covers 30+ resources; this repo covers the 13 most central to day-to-day pest control operations (81 tools). Not yet covered: access control profiles, application methods, appointment reminders, changelogs, customer flags, doors/knocks (door-to-door sales tracking), forms, GL accounts, groups, insects (reference data), locations, reviews, spots (route stop slots), teams, time clock, and units. Contributions welcome.

What's next

See ROADMAP.md for the rest of the planned series and the pattern this repo follows.

Built by BackCrew

This project is free and open for anyone to use, copy, or build on. That's the whole point.

It's also a sample of the kind of work BackCrew does: we build tools, automations, and AI setups like this one for pest control and field service businesses, including the business-logic layer (collections, capacity planning, escalation rules) that intentionally isn't part of this open repo. If you like what this does but don't want to set it up and maintain it yourself, or you want something built specifically for how your business runs, that's exactly the kind of project we take on.

Want this set up for you? Reach out: [email protected]

No pressure either way: everything above works on its own, for free.

License

MIT