MCP Data Model

Use this page to navigate the objects returned by ModernLoop MCP tools. Start a new session with get_me: it identifies the acting user, organization, and scopes available to the connection.

Object graph

An organization contains jobs, users, interview modules, templates, task queues, schedules, and their related records.

Organization
├── Jobs ──┬── Job stages
│          └── Applications ── Candidate
│                            └── Scheduling tasks ── Task queue
│                                                  └── Assignee (user)
├── Schedules ── Interview events ── Application / Candidate / Users
├── Users ── Interview-module memberships ── Interview modules
└── Email and calendar templates

An application connects a candidate to a job and has a current job stage.
A scheduling task is created for an application and a job stage. It can be assigned to a user and placed in a task queue.
A schedule is a group of interview events. Events identify their participants and connect back to the relevant application and candidate.
An interview module defines training requirements. Its memberships connect users to that module and record their training progress.
Templates are searchable reference records. No current MCP write or scheduling tool consumes a template directly.

Canonical ID prefixes

Canonical external IDs are a prefix, an underscore, and a 32-character hexadecimal UUID body. For example, can_a1b2c3d4e5f64789a1b2c3d4e5f64789 is a candidate ID.

Object	Prefix	Example
Candidate	`can_`	`can_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Application	`app_`	`app_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Job	`job_`	`job_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Job stage	`stg_`	`stg_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Scheduling task	`tsk_`	`tsk_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Task queue	`que_`	`que_a1b2c3d4e5f64789a1b2c3d4e5f64789`
User	`usr_`	`usr_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Interview module	`mod_`	`mod_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Interview event	`int_`	`int_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Schedule	`sch_`	`sch_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Template	`tpl_`	`tpl_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Organization	`org_`	`org_a1b2c3d4e5f64789a1b2c3d4e5f64789`
User attribute	`att_`	`att_a1b2c3d4e5f64789a1b2c3d4e5f64789`
User attribute value	`atv_`	`atv_a1b2c3d4e5f64789a1b2c3d4e5f64789`
Help article	`hlp_`	`hlp_a1b2c3d4e5f64789a1b2c3d4e5f64789`

The API also accepts UUID forms where the tool schema permits them, but use canonical prefixed IDs in conversation and stored references so the object type is clear.

Recommended discovery sequences

Use list tools to discover an ID, then use the matching get tool before a consequential update.

Goal	Recommended sequence
Orient a new connection	`get_me` → `get_organization` when `organization:read` is available
Inspect a candidate’s progress	`list_candidates` → `get_candidate` → `list_applications` → `get_application`
Create a scheduling task	`list_candidates` → `list_applications` → `get_application` → `list_job_stages` (with `job_id` or `ids`) → `get_job_stage` → user confirmation → `create_scheduling_task`
Triage your assigned tasks	`get_me` → `list_scheduling_tasks` with `my_tasks: true` → `get_scheduling_task` for detail
Investigate scheduling	`list_applications` → `list_scheduling_tasks` → `get_scheduling_task` → `list_schedules` or `list_interview_events`
Select an assignee	`list_users` → `get_user` → `update_scheduling_task` after confirmation
Inspect interview training	`list_interview_modules` → `get_interview_module` → `list_interview_module_members` → member stats
Find a queue’s work	`list_task_queues` → `get_task_queue` → `list_scheduling_tasks` filtered to that queue
Answer a how-to or troubleshooting question	`list_help_articles` with a focused query → `get_help_article` for the best match

Read the current record before an update. For destructive operations, explicitly confirm the target and impact with the user first.

Pagination and filters

List tools return a cursor when more results are available. To fetch the next page, pass pagination.next_cursor back unchanged and retain the exact same filters and sort context used on the first request. Do not reuse a cursor with a different name, status, date, ID, or other filter; start a new list request instead. List-tool filters are conjunctive when more than one is supplied: each result must satisfy every provided filter. Start with a narrow, stable query when you expect to paginate. Omit a filter parameter to skip that filter. Providing an empty array filter (for example assignee_ids= or ids: []) returns VALIDATION_FAILED; supply at least one value or omit the parameter entirely. list_job_stages requires at least one of ids or job_id. list_scheduling_tasks accepts my_tasks: true as shorthand for tasks assigned to the acting user; it cannot be combined with assignee_ids. When a related object is missing or inaccessible, nested relation fields are returned as null rather than placeholder records (for example task application, candidate, job, job stage, or note author; schedule application; user attribute_name or module).

Naming conventions in tool inputs

Get tools commonly take a camelCase path-style ID such as candidateId, jobStageId, or taskQueueId. List and write payloads can use snake_case fields. Use the input schema returned by tools/list for the exact field names and required values for your client.

Connect

Object graph

Canonical ID prefixes

Recommended discovery sequences

Naming conventions in tool inputs

Further reading

​Object graph

​Canonical ID prefixes

​Recommended discovery sequences

​Pagination and filters

​Naming conventions in tool inputs

​Further reading

Object graph

Canonical ID prefixes

Recommended discovery sequences

Pagination and filters

Naming conventions in tool inputs

Further reading