This reference explains the main actions available through the ATZ CRM MCP Server and how AI assistants can search, read, create, or update CRM data through controlled tools.
Quick Answer
MCP supports search/read tools for core CRM data and non-destructive write actions for supported records. Deals are currently read/search-only. Review all write actions before approval.
General Rules
- List and search actions are paginated.
- Search and read actions do not modify records.
- Write actions are non-destructive.
- Delete, merge, archive, and bulk-delete actions are not exposed.
- Create actions use retry-safe duplicate handling. The default behavior fills only missing fields on the matching record.
- Account-specific custom fields are supported except file-type fields.
- Candidate file links and resume links are restricted by default in summary tools.
- User-provided CRM data should be reviewed before sharing externally.
Search and Context Tools
MCP includes tools for account context, Boolean Search guidance, candidate field descriptions, and metadata lookup.
Use these when an assistant needs to understand available fields, custom field IDs, employment types, industries, statuses, stages, activity types, call log types, note types, currencies, or users.
Boolean Search
MCP supports Boolean Search for candidates, jobs, organizations, contacts, and deals.
Useful operators include:
| Operator | Example | Meaning |
|---|---|---|
| AND | React AND London | Both terms should match |
| OR | Java OR Kotlin | Either term can match |
| NOT | London NOT contractor | Exclude the second term |
| Quoted phrase | "Account Manager" | Match the exact phrase |
Supported Entity Actions
| Entity | Search/List | Read | Create | Update | Notes |
|---|---|---|---|---|---|
| Candidates | Yes | Yes | Yes | Yes | Includes individual work and education history create/update |
| Jobs | Yes | Yes | Yes | Yes | Can include pipeline briefs and recent activity context |
| Organizations | Yes | Yes | Yes | Yes | Can include contacts, open jobs, and notes |
| Contacts | Yes | Yes | Yes | Yes | Can link to organizations |
| Deals | Yes | Yes | No | No | Read/search-only |
| Matches | Yes | Limited | Yes | Stage update | Candidate-job matching workflows |
| Notes | Yes | Limited | Yes | No | For supported entities |
| Activities | Yes | Yes | Yes | Yes | Tasks, meetings, follow-ups |
| Call Logs | Yes | Yes | Yes | Yes | Incoming/outgoing call records |
| Folders | Yes | Yes | Yes | Yes | Add/remove records from folders |
| Metadata | Yes | No | No | No | Lookup values for workflows |
Candidate Tools
Candidate tools can search profile data, skills, location, tags, current role, current organization, resume/search document text, work history, education history, notes, and custom fields.
Common candidate write fields include first name, last name, email, phone, current position, current organization, source, city, state, country, skills, tags, owner ID, and supported custom fields.
Candidate history actions can add or update one work or education row without replacing the rest of the profile:
| Action | Main fields |
|---|---|
| Create/update work history | Candidate slug, row ID for updates, title, employer, employment type, industry, location, salary, current-role flag, dates, description |
| Create/update education history | Candidate slug, row ID for updates, school, qualification, specialisation, grade, location, dates, description |
Each candidate can have up to 10 work-history rows and 10 education-history rows. End dates must not be before start dates. Marking a work row as current clears its end date. Use the metadata action with employment_types or industries before sending their IDs.
Example prompts:
Add a current work-history entry to candidate_abc123: Senior React Engineer at Acme Ltd in London, started 2023-04-01, full time.
Update education row 42 for candidate_abc123 and set the qualification to BSc Computer Science and grade to First.
Example prompt:
Find candidates with React experience in London. Include work history and education history. Show the top 10 results with current role, current company, skills, and location.
Job Tools
Job tools can search job title, organization, primary contact, funnel, contract details, location, salary frequency, category, qualifications, industry, skills, description, status, owner, tags, and custom fields.
Common write fields include position name, organization slug, primary contact slug, headcount, description, location, skills, tags, status ID, talent funnel ID, and supported custom fields.
A job’s primary contact must belong to the selected organization. Creating a job records its initial status history, and changing status_id records another timeline entry. Ask the assistant to include a status comment when the reason matters.
Organization links and primary-contact links can be cleared without deleting either record. Job moves also update the linked organizations’ total job counts.
Example prompt:
Summarize the pipeline for job_xyz123. Group candidates by stage, identify bottlenecks, and suggest next actions.
Organization and Contact Tools
Organization tools support client/company search, brief creation, create, and update. Contact tools support client-contact search, create, and update.
Contacts can be linked to an organization during create or update, or unlinked later without deleting the contact. ATZ CRM validates that organization slugs belong to the connected account.
Example prompt:
Prepare a client meeting brief for organization_abc123. Include key contacts, open jobs, recent notes, and follow-up actions.
Match and Pipeline Tools
MCP can list matches, create candidate-job matches, and update match stages.
Example prompt:
Move candidate_abc123 to the interview stage for job_xyz123 and add a comment that the client requested a technical interview.
Notes, Activities, and Call Logs
MCP can list and create notes for supported entities, create and update activities, and create or update call logs.
Example prompts:
Add a note to candidate_abc123: Candidate is available for interviews next week and prefers remote roles.
Log an outgoing call with candidate_abc123 for 5 minutes. Notes: Left voicemail and will try again tomorrow.
Folders
MCP folders map to ATZ CRM focus groups. Supported folder entities include candidates, jobs, contacts, organizations, and deals.
MCP can list folders, create folders, update folder details, list folder records, add records, and remove records from folders.
Removing records from a folder removes only folder membership. It does not delete the underlying record.
Troubleshooting
The AI Assistant Asks for Many Approvals
Ask for a brief or summary instead of many individual record opens where possible.
Search Results Are Not Expected
Use more specific Boolean Search terms such as React AND London, C++ AND London NOT contractor, or "Account Manager" AND SaaS.
Write Action Did Not Run
Your AI client may require confirmation. Review and approve the tool request if correct.
A Duplicate Was Returned Instead of a New Record
This is the default safety behavior. ATZ CRM fills only blank fields on the matching record. Ask for duplicate policy reject when you want an error, or create_new only when a separate record is intentional.
A Job Contact Link Was Rejected
Confirm that the contact belongs to the organization selected for the job. Link the contact to that organization first or choose a contact already linked to it.
Deals Cannot Be Updated
Deal MCP actions are currently read/search-only.
Security Best Practices
- Treat the MCP URL like a password.
- Rotate the URL if exposed.
- Disable MCP when not in use.
- Review every write action before approval.
- Verify AI-generated messages, summaries, and recommendations before sharing externally.
FAQs
Can MCP create a shortlist folder?
Yes. It can create folders and add supported record slugs.
Can MCP search notes?
Yes. Search tools can include notes where supported.
Can MCP expose file links?
File links are restricted by default in summary tools for security.
Can MCP write custom fields?
Yes. Ask the assistant to list metadata for the entity first, then use the returned custom field ID and a value matching its type. File custom fields are read-only through MCP.