What This Guide Is
The Redlist MCP lets you talk to your Redlist data in plain English through Claude. Instead of clicking through screens to spot missing images, overdue work orders, or routes without forms, you ask a question — Claude pulls the data and answers.
This guide has two parts:
Part 1 — For internal teams. Built for CSMs and account managers helping customers audit and build out their data. Includes every tool, ready-to-paste prompts, and a guided demo flow.
Part 2 — For Redlist customers. A plain-English explanation of what the MCP can do for them, how to get connected, and the questions they can ask on day one.
In a nutshell: The MCP is a bridge between Claude and your Redlist account. Claude can read your data (assets, routes, forms, compliance) and — with an admin's permission — help bulk-import new data.
PART 1 — For Internal Teams
Use this section when sitting with a customer (or prepping for a call) to demo what the MCP can surface, or run an audit against their environment to find gaps worth fixing.
Getting Connected
Two clients are supported: Claude Desktop (point-and-click, best for demos and customer-facing sessions) and Claude Code (CLI, best for power users and scripting).
Claude Desktop
Open your Claude Desktop config file:
-%APPDATA%\Claude\claude_desktop_config.json(Windows)
-~/Library/Application Support/Claude/claude_desktop_config.json(macOS)Add the Redlist MCP server under
mcpServers:{ "mcpServers": { "redlist": { "url": "https://mcp.yourredlist.com/mcp" } } }Restart Claude Desktop.
On the first tool call, a browser window opens for the Redlist login. Sign in, complete MFA if prompted, and click Allow on consent.
Consent is remembered for a year — subsequent sessions skip straight to the data.
Claude Code
Add the MCP server through Claude Code's settings UI (or edit
~/.claude.json) with the URL pointing at/mcpon the MCP server.Run
claudein your terminal.Pick Authenticate on the Redlist server card. A browser opens for OAuth.
After "All set" appears, return to the terminal and select Reconnect.
Run
pingas a smoke test — Claude should return your user ID.
If something breaks:
"Connects then immediately 401s" — almost always an OAuth Issuer mismatch. The Issuer in App Configuration must exactly match the URL the client uses (no trailing slash, no /mcp suffix).
Self-signed dev cert with the Inspector — set
NODE_TLS_REJECT_UNAUTHORIZED=0in the same shell before running npx.Stale OAuth state after restarting the MCP server — click "Clear OAuth State" in the Inspector before reconnecting.
How a Session Flows
Every session follows the same shape:
Authenticate — happens automatically on first tool use.
Pick your shards — call
set_active_shardsonce near the start. Every downstream tool defaults to this scope, so you don't have to repeat shard IDs.Ask questions — Claude picks the right tool, runs it across your active shards, and brings the data back.
For writes, stage then apply — imports stage in Redis first. Nothing hits the database until you say apply with
confirm: true.
Pro tip for demos: For drift/comparison stories, pick two shards belonging to the same customer (different sites) or two tenants on the same template pack. The "one-page tenant health report" prompt (section 9 below) is the strongest single demo — it pulls from audit, overdue, submissions, and compliance tools in one reasoning pass.
Tool Inventory
Session setup
Tool | What it does |
ping | Smoke test. Returns the user ID from the JWT so you can confirm auth is wired up. |
list_accessible_shards | Shards the signed-in Redlist user has access to. |
set_active_shards | Commit a session scope — which shards data tools should run against. |
get_active_shards | Read the current active shard set. |
Form templates
Tool | What it does |
list_form_templates | Summary list of form templates per shard — id, name, title, description, version, timestamps. |
get_form_template | Full content of one template (FormSections / FormSettings / DynamicFormSections JSON) fetched from every requested shard. |
Products
Tool | What it does |
list_products | Lightweight product summary per shard — id, name, number, description, pricing, stock levels, flags. |
get_product | Full product record from each requested shard — inventory, pricing, vendor, categorization, location. |
Routes
Tool | What it does |
list_routes | Routes with recurrence summary plus counts of component tasks, total/open/completed/cancelled work orders. |
get_route_details | Full route picture: recurrence, component tasks, open work orders, recent completed, recent cancelled. |
Compliance
Tool | What it does |
get_route_compliance | For a route in a window: bucketed counts (completedOnTime, completedLate, open, overdue, cancelled) plus sampled work orders per bucket. |
list_overdue_work_orders | Open work orders with NextDue before the as-of date. Optional route/asset filter. Each sample includes daysOverdue. |
Audits
Tool | What it does |
audit_missing_images | Components and assets with no image attached. |
audit_missing_form_templates | Component tasks with no FormTemplateID, plus routes whose component tasks are entirely without form templates. |
audit_missing_component_tasks | Components that have no active component tasks. |
audit_asset_configuration | Rollup audit: assets with no active components, assets with no responsible employee, components with no active tasks. |
list_route_forms | Distinct form templates attached to a route via its component tasks — plus component tasks on the route with no form attached. |
Asset hierarchy
Tool | What it does |
list_asset_groups | Hierarchical AssetGroups with child-group and asset counts. Omit parentId for top level; pass parentId to drill down. |
get_asset_hierarchy | Full snapshot of a single asset: the asset record, all AssetGroups, AssetSections, Components with ComponentTasks inline, and Custom.FieldValues. |
list_custom_fields | Catalog of Custom.CustomFields definitions per shard — name, dataType, scanType, value count. |
Form submissions
Tool | What it does |
list_form_submissions | Counts (total, submitted, failed, uniqueSubmitters) plus sampled submissions per shard in a date range. Optional template filter. |
form_submission_activity_by_day | Per-shard daily time series of submission counts and unique submitters. |
Lookups
Tool | What it does |
list_lookups | Returns id + label rows for a named lookup table (AssetType, AssetMake, AssetModel, AssetClass, AssetStatus, Location, Region, UnitOfMeasure, FieldRank, TaskType, MaintenanceMethodType, ApplicationType). Call before staging so the AI uses real ids instead of guessing. |
Import (write) — admin only
Requires SystemAdmin, Administrator, ClientManager, or BrandAdmin role on the target shard. Imports follow a stage-then-apply pattern — nothing writes until you call import_session_apply with confirm: true.
Tool | What it does |
import_session_start | Start a single-shard, 60-minute import session. Returns importSessionId. |
import_session_get | Snapshot of a session — staged items with tempIds, kinds, and (after apply) realIds or errors. |
import_session_preview | Ordered apply plan plus validation warnings. Does not write. Call this before apply. |
import_session_apply | Applies staged items via Redlist.WebApi. Requires confirm: true. Partial failures are NOT rolled back. |
import_session_discard | Delete the session and its staged plan without writing anything. |
stage_asset | Stage a new Asset. tempId is caller-chosen; other staged items can reference this asset by tempId. |
stage_asset_group | Stage a new AssetGroup. Parent can be an existing id or a tempId from earlier in the session. |
stage_asset_group_asset | Stage the junction row placing an Asset into an AssetGroup. |
stage_asset_section | Stage a subdivision of an asset. |
stage_component | Stage a new Component on an Asset (and optionally an AssetSection). |
stage_component_task | Stage a maintenance ComponentTask attached to a Component. Optionally attach a FormTemplate. |
stage_component_task_product | Stage a Product attachment to a ComponentTask — the consumable used and how much per application point. |
stage_lookup | Stage a new row in a simple lookup table when an FK value doesn't yet exist in the shard. |
stage_asset_model | Stage a new AssetModel under an AssetMake. |
stage_product | Stage a new Product (part / SKU / consumable). |
Demo Prompts
1. Session setup (warm-up)
Ping the Redlist MCP server and tell me who I am authenticated as.
Show me which Redlist shards I can access, then pick two of them as my active set for this session.
2. Form templates across tenants
List all active form templates named something like "inspection" across my active shards and tell me how many each tenant has.
Take the first form template from shard A, find one with a similar name in shard B, get the full content of both, and tell me what is different between them.
3. Products
Find any oil-related products in my active shards and show me the difference in how each tenant prices them.
Pick a product id from shard A. Does that exact SKU exist in any other active shard? If so, compare the stock levels and bin locations.
4. Routes and drift
Which routes show up across multiple shards with similar names? List the top matches by name overlap.
For route {routeId}, give me the full details: recurrence, component tasks, open work orders, and recent history. Tell me if any of the recent work orders have tasks that are not in the template (ad-hoc work) or are missing template tasks (skipped work).
Compare the component-task list of route {routeId} across every shard it exists in. Where do they diverge?
5. Compliance and overdue
For route {routeId}, give me compliance for the last 90 days across my active shards. Tell me the on-time completion rate and highlight which shard is worst.
Show me all overdue work orders across my active shards, sorted by how many days late they are. Group the summary by shard and include anything more than 30 days overdue.
6. Audits
Audit my active shards for components and assets that do not have images attached. Give me a count per shard and call out anything with more than 100 missing.
Find component tasks and whole routes that do not have form templates assigned. For any route that is totally missing forms, try list_route_forms to confirm it is empty.
Run the asset configuration audit across my active shards. Summarize the three gap types and tell me which shard has the biggest configuration debt overall.
7. Forms a route uses
For route {routeId}, what forms would a technician actually fill out when running it? Include how many tasks on the route reference each form.
8a. Asset hierarchy
Across my active shards, list the top-level asset groups and show me how many assets and child groups each one contains.
I know an asset id in shard A. Fetch its full hierarchy: which groups it belongs to, its sections, components, and the component tasks on each component. Summarize what kind of equipment this is and what maintenance is configured for it.
List the custom fields defined in my active shards. Which ones are system-defined vs custom, and how many values exist for each? Flag any that are defined but have zero values — those are probably unused.
8b. Form submissions
Across my active shards, how many form submissions happened in the last 30 days? Break down by shard with total, submitted, failed, and unique submitters.
Show me the daily submission trend for form template {formTemplateId} in the last 60 days. Note any days with unusually high or low activity.
8c. Imports (writing data)
Start an import session targeting shard X with the label "demo asset import". Then stage three assets with unitIds ASSET-A, ASSET-B, ASSET-C (tempIds t1/t2/t3). Call preview to show me the plan before I approve.
Looks good. Apply the session with confirm: true and tell me which assets were created with which AssetIDs.
I realized I do not want to go through with the import. Discard the session.
Before staging, call list_lookups for AssetType and Location to get the ids I should use. Then stage an asset with a matching AssetTypeID and LocationID.
Build a full asset import in one session: stage AssetGroup g1 "Plant 3", Asset a1 "Pump-101" with TypeID/LocationID from list_lookups, AssetGroupAsset linking them, AssetSection s1 "Hydraulics" on a1, Component c1 on a1 in s1, ComponentTask ct1 (frequencyDays=30, taskDurationMinutes=15) on c1, and ComponentTaskProduct ctp1 attaching a product with volumePerPoint=2 pointsPerApplication=1. Preview, then apply.
9. Cross-tool reasoning (the strongest demo)
I want to understand PM compliance risk across my tenants. Pull overdue work orders, then for the route of each overdue WO, get its compliance numbers for the last 90 days. Tell me which routes are chronically late versus just late right now.
Do a health check on shard A: run all the audit tools, get the form submission count for the last 30 days, count overdue work orders, and give me a one-page tenant health report with actionable gaps.
Limits to know about:
Import sessions cap at 500 staged items. Larger imports need to chunk into multiple sessions.
Read tools sample up to 100 rows per shard (500 max, 1000 for lookups). Counts are reported separately so you can tell when a sample is truncated.
Active shard set persists for ~30 days. Set it once, forget it.
Partial failures on import are NOT rolled back. Each item reports its own success/error independently.
PART 2 — For Redlist Customers
This section is for the people who actually use Redlist day to day — managers, planners, supervisors, and admins. If you've ever wished you could just ask your Redlist account a question instead of clicking around for it, this is for you.
What Is the Redlist MCP?
The MCP ("Model Context Protocol") is a connection between Claude — Anthropic's AI assistant — and your Redlist account. Once connected, you can ask Claude questions about your data and it will pull the answer directly from Redlist.
Think of it as an extra teammate who can read everything in your Redlist account in seconds and summarize what they found. It does not replace Redlist — it works on top of it.
What It Can Do
Answer questions about your assets, routes, components, products, and forms
Audit your data — find assets without components, components without tasks, tasks without forms, missing images, and so on
Compare data across multiple sites to spot drift between locations using the same template
Track compliance — on-time vs. late completions, overdue work orders, who's submitting forms
Help admins bulk-import new data (assets, asset groups, components, tasks, products) with a preview-before-commit workflow
What It Can't Do (Today)
Edit or delete existing data — the MCP is read-only except for new imports
Upload files or images directly — that still happens in the Redlist app
Work without permission — imports require an admin role on the target site
Getting Connected
You'll need Claude Desktop installed and your Redlist credentials. The first connection takes about two minutes.
Install Claude Desktop from the Anthropic website if you don't have it already.
Your Redlist contact will share the MCP server URL. Add it to your Claude Desktop config — your contact will walk you through where the file lives.
Restart Claude Desktop. The first time you ask it something about Redlist, a browser tab opens asking you to log in.
Sign in with your normal Redlist credentials. If your account uses multi-factor authentication, you'll get the usual TOTP prompt.
Click Allow on the consent screen. This is asking your permission to let Claude read your Redlist data.
That's it. You won't see the consent screen again for a year. Your Redlist permissions still apply — Claude can only see what you can see.
On security and permissions:
Claude uses your Redlist account, not a shared service account. Everything it can see is what you can see — same roles, same site access.
All write actions (imports) require an admin role on the target site. Non-admins simply can't trigger them.
Nothing writes to Redlist without a clear confirmation step. Imports stage first, you preview, then you explicitly approve.
Your Redlist password is never re-transmitted after the initial login.
Step 1: Pick Your Scope
If you have access to multiple Redlist sites, start by telling Claude which ones you want to work with. This stays set for the rest of the conversation.
Show me which Redlist sites I can access, then pick the ones for Plant A and Plant B as my active set for this session.
Questions to Ask
"What's in my account?"
Across my active sites, list the top-level asset groups and tell me how many assets and child groups each one contains.
List all active form templates in my account. Group them by site and show me how many each one has.
How many products are in my account, and what's the total inventory value if I add up stock × price?
"Where are the gaps?"
Audit my account for components and assets that don't have images attached. Give me a count per site and call out anything with more than 100 missing.
Find component tasks and entire routes that don't have form templates assigned. For any route that is totally missing forms, double-check it's actually empty.
Run the asset configuration audit. Tell me which assets don't have components yet, which components don't have tasks, and which assets don't have a responsible employee assigned.
List custom fields that are defined but have zero values across my sites — those are probably unused and worth removing.
"How are we doing on compliance?"
Show me all overdue work orders sorted by how many days late they are. Group by site and highlight anything more than 30 days overdue.
For my main inspection route, give me the compliance numbers for the last 90 days. What's the on-time completion rate?
Which routes are chronically behind? Pull overdue work orders and tell me which routes show up repeatedly versus the ones that are just one-off late.
"Are my sites set up consistently?"
Which routes show up across multiple sites with similar names? List the top matches by name overlap.
Compare the component-task list of my Daily PM route across every site it exists in. Where do they diverge?
Take an inspection form template from Site A, find the matching one in Site B, and tell me what's different between them.
"What's my form activity look like?"
How many form submissions happened in the last 30 days? Break down by site with total, submitted, failed, and how many unique submitters.
Show me the daily submission trend for the daily inspection form over the last 60 days. Note any days with unusually high or low activity.
"Give me a health check."
Do a health check on my main site: run all the audit tools, get the form submission count for the last 30 days, count overdue work orders, and give me a one-page health report with actionable gaps.
Bulk Imports (Admins Only)
If you have an admin role on a site, the MCP can help you build out new data quickly — without spreadsheet uploads or manual clicking.
Imports follow a stage → preview → apply pattern. You describe what you want, Claude stages it, you review the plan, and then you explicitly approve. Nothing writes until you say confirm.
Simple example: import three assets
Start an import session for my main site with the label "Q2 new assets". Stage three assets with unitIds PUMP-201, PUMP-202, PUMP-203. Use the AssetType and Location ids you already know exist in the site. Preview the plan before I approve.
Claude will show you a preview. If it looks right: Looks good. Apply the session with confirm: true and tell me what asset IDs were created.
Changed your mind? Just say so: I realized I don't want to go through with the import. Discard the session.
Important caveats for imports:
Sessions cap at 500 staged items. Bigger imports need to be chunked.
Sessions expire after 60 minutes. Plan accordingly.
Partial failures are NOT rolled back. If 9 of 10 items succeed and 1 fails, you keep the 9 — Claude will tell you which one failed so you can fix and retry.
Imports always run against one site at a time, not across multiple sites.
Tips for Getting the Best Results
Set your scope once. Call out which sites you want to work with at the start of the conversation. Everything else defaults to that scope.
Be specific about the time window. "The last 30 days" beats "recently."
Ask for grouping. "Group by site" or "sorted by days overdue" turns a raw count into something you can act on.
Stack questions. Claude is good at chaining tools. "Find overdue work orders, then for each route show me the compliance for the last 90 days" works in one prompt.
Use it as a sanity check. Before a big template rollout or audit, ask Claude to compare two sites and tell you what's different.
Frequently Asked Questions
Can Claude see my password?
No. You log in through Redlist's normal login screen in your browser. The MCP never sees or stores your password — only short-lived tokens that prove you've authenticated.
What happens if I'm not an admin?
You can use every read and audit tool. Import tools require an admin role on the target site. Non-admins get a clean error message instead of being able to trigger an import.
Will Claude accidentally delete or change my data?
No. The MCP cannot delete or edit existing records — it's read-only except for new imports. Imports themselves require an explicit confirmation step, so accidental writes aren't possible.
How long do I stay logged in?
Your session lasts about 30 days of activity. If you use it weekly, you'll basically never have to log in again. After 30 days of inactivity you'll be prompted to re-authenticate.
Does it work on mobile?
Today, the MCP works with desktop Claude clients (Claude Desktop on Mac/Windows, Claude Code in a terminal). Mobile Claude support is on the roadmap but not available yet.
Can my team share one connection?
Each person connects with their own Redlist credentials. This is by design — it means audit logs in Redlist always show who did what, and each person only sees the sites their account has access to.
Who do I contact if something breaks?
Reach out to your Redlist account team or CSM. The most common issue is a login problem on the first connection — they can usually resolve it in a couple of minutes.