Ask FieldRoutes (fieldroutes-mcp)

Read-only MCP server so pest and lawn owners can ask FieldRoutes questions in plain English — in Claude, ChatGPT, or Cursor.

Sister product to Ask Fieldwork. Same Relay pattern: owner-shaped tools with an answer string, /connect vault (no Terminal-first setup), lookup only.

Why this exists

Most FieldRoutes MCPs are thin API wrappers: search_tickets, env vars in JSON, pip + Terminal. Owners bounce.

Ask FieldRoutes leads with questions owners actually ask:

Ask…	Tool
How many customers do I have?	how_many_customers
Find customer Smith	find_customer
Who owes me money?	who_owes_me_money
What’s on the schedule?	whats_on_the_schedule
Who are my technicians?	who_are_my_technicians
How are my routes doing?	how_are_my_routes_doing

Lower-level search_* / get_* tools stay available as a fallback. Writes (create/update/cancel) are refused.

Auth

FieldRoutes uses API key + token (Settings → API), sent in the JSON body as authenticationKey / authenticationToken.

Optional company subdomain → https://{subdomain}.pestroutes.com/api.

Quick start (local stdio)

cd fieldroutes-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# fill FIELDROUTES_AUTHENTICATION_KEY and FIELDROUTES_AUTHENTICATION_TOKEN

Point Cursor / Claude at scripts/run_mcp.sh (see mcp.json.example).

Hosted connect (no Terminal)

./scripts/run_mcp_http.sh
# open http://127.0.0.1:8000/connect

Paste key + token → encrypted SQLite vault → bearer token for Streamable HTTP MCP at /mcp.

URL	Role
/	Relay landing
/fieldroutes	Ask FieldRoutes product page
/connect	Paste credentials → token
/mcp	Streamable HTTP MCP
/healthz	Health

Deploy

• Vercel (vercel.json): static landing/ only (marketing).
• Docker: full MCP + /connect + vault. Set FIELDROUTES_VAULT_SECRET and optionally FIELDROUTES_PUBLIC_BASE_URL.

Safety

• Client allowlists only search and get.
• Tool annotations mark everything read-only.
• Vault stores encrypted credentials; connect tokens are hashed at rest.

Vs thin wrappers

	Typical FieldRoutes MCP	Ask FieldRoutes
Tools	API-shaped (search_tickets)	Owner-shaped + answer
Setup	pip + env + JSON	/connect vault
Writes	Often on by default	Off
Technicians	Often missing	who_are_my_technicians
Audience	Developers	Owners

License

MIT