ClarityLoop MCP Data Catalog
This page describes the data and actions available through the ClarityLoop MCP server for AI clients such as ChatGPT, Claude, MCP Inspector, and IDE assistants.
Use it when you want to build dashboards, metrics, reports, analytics workflows, or agent-driven people operations on top of live ClarityLoop data.
How to Think About the MCP Server
MCP exposes tools, not REST endpoints. Your client connects to the MCP server once, then the AI model calls named tools such as searchPeople, getLeadershipInsights, or getSurveyInsights.
Connection URLs:
https://mcp.clarityloop.com/mcphttps://mcp.clarityloop.com/sse
Authentication options:
- OAuth-style MCP client flow
- API key header:
X-ClarityLoop-Api-Key: <your_mcp_api_key>
Every response is returned as structured JSON text. List-style tools return paging metadata where paging is supported.
Access and Scope
MCP access follows the ClarityLoop account that authenticated the client. It is not a workspace-wide export credential.
- Each MCP key is personal to the person who created it.
- A user can only see data permitted by their ClarityLoop role and normal product visibility.
- Managers generally see their own reporting line.
- Workspace owners can use owner-only filters for leader, department, role, affiliation, and member attribute analysis.
- Survey owners can filter survey insights. Survey leaders can view scoped survey insights, but cannot use owner-only filters.
- Write tools can create or update records in ClarityLoop. AI clients should confirm with the user before calling them.
Common Parameters
Many tools share these conventions:
userId: ClarityLoop user ID. UsesearchPeopleorgetCurrentUserto resolve it.fromDate,toDate,startDate,endDate: date strings inYYYY-MM-DDformat unless the field says it needs an ISO datetime.page: zero-based page number.pageSize: number of results to return. Most list tools cap this at 20.filters: object used to narrow by person, date range, owner scope, department, role, affiliation, or member attributes.meetingRef: opaque meeting reference returned byfindMeetings. Pass it back to meeting detail and write tools.
Recommended Integration Pattern
For analytics, use a staged extraction pattern:
- Call
getCurrentUserto identify the user, workspace, role, level, affiliations, and available scope. - Call
getPeopleFilterOptionsto load reusable dimensions such as departments, roles, levels, affiliations, and member attributes. - Call
searchPeopleorgetDirectReportsto build the people population for the analysis. - Pull the relevant signal families: feedback, goals, meetings, surveys, work context, values, career framework, and leadership insights.
- Store normalized snapshots in your own analytics system with timestamps and source tool names.
- Build derived metrics from stable IDs, dates, counts, statuses, and score fields.
For conversational agents, use a narrower pattern:
- Start with
getCurrentUser. - Resolve people with
searchPeople. - Load the few records needed for the task.
- Ask for confirmation before calling any write tool.
Analytics Data Domains
People and Organization
Use this domain to build the dimensional model for your dashboards.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
getCurrentUser | Read | Current user, workspace, title, level, affiliations, member attributes, workspace role |
getPeopleFilterOptions | Read | Career framework summary, departments, roles, levels, affiliations, member attribute options, workspace search filters |
searchPeople | Read | Workspace members with profile, title, level, affiliations, attributes, active/current status, role |
getDirectReports | Read | Manager-to-report relationships and report profiles |
Useful data points:
- person ID, name, email
- title
- workspace member role
- active and current status
- department, role, track, level, level sequence
- affiliations and primary affiliation
- member attributes and whether an attribute is sensitive
- manager reporting line through direct reports
Dashboard uses:
- people directory dimensions
- team and reporting-line membership
- active headcount by department, role, level, affiliation, or attribute
- manager span of control
Example prompts:
Use getCurrentUser, then searchPeople. Build a table of active people grouped by department and level.
Use getPeopleFilterOptions to find the Engineering department ID, then searchPeople for active members in that department.
Feedback and Growth Signals
Use this domain to understand feedback flow, themes, recognition, coaching opportunities, and individual growth patterns.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
findReceivedFeedback | Read | Feedback received by a person, with sender, summary, sentiment, status, request ID, sharing flags, linked values, strengths, growth opportunities, timestamps |
findGivenFeedback | Read | Feedback given by the current user, with recipient, summary, sentiment, status, linked values, strengths, growth opportunities, timestamps |
findIncomingFeedbackRequests | Read | Feedback requests assigned to the current user, request subject, recipients, response status/counts, timestamps |
findSentFeedbackRequests | Read | Feedback requests sent by the current user for a person, recipients, response status/counts, manager mode, timestamps |
getFeedbackDetails | Read | Full feedback body, description, SBI/SSC/STAR structures, linked values, linked strengths, linked growth opportunities, evidence contexts |
getGrowthSignals | Read | Strengths, growth areas, linked values, sentiment scores, feedback given/received counts for a person |
giveFeedback | Write | Create/update draft feedback or share feedback |
requestFeedback | Write | Send feedback requests to one or more people |
Useful data points:
- feedback ID and request ID
- sender and recipient user IDs
- summary and detailed description
- feedback status:
DRAFT,SHARED - sentiment score
- anonymous flag
- manager sharing flags
- linked company values
- linked strengths and growth opportunities
- structured SBI, SSC, and STAR entries
- evidence links and metadata
- created and updated timestamps
- request recipients and whether they responded
- request response counts
Dashboard uses:
- feedback received count by person and period
- feedback given count by person and period
- feedback request response rate
- sentiment trends by person, team, or reporting line
- top growth themes
- top strengths
- company value recognition distribution
- feedback network analysis using sender and recipient IDs
Example prompts:
For each direct report, call getGrowthSignals for the last quarter. Compare sentiment, feedback volume, strengths, and growth areas.
Find feedback received by this person in the last 90 days, then open the details for the strongest evidence items and summarize recurring themes.
Goals and OKRs
Use this domain to analyze execution, goal health, and the connection between development signals and goals.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
findGoals | Read | One person's goals, key results/actions, statuses, dates, scores, links, owner |
getGoalDetails | Read | Full goal or key result/action details, comments, source links and metadata |
createGoal | Write | Create a draft or published goal |
addGoalItem | Write | Add a key result/action to a goal |
linkToGoal | Write | Link values, feedback, growth opportunities, or levels to a goal |
updateGoalProgress | Write | Update progress and optionally add a comment |
Useful data points:
- goal ID and key result/action ID
- owner ID
- title and description
- goal type:
WORK,GROWTH,BOTH - status:
DRAFT,PUBLISHED,CANCELLED - start and end dates
- current score
- cascade and parent objective ID
- key result measurement type:
MANUAL,JIRA,LINEAR,FORECAST - key result/action status
- source links and metadata
- linked records:
VALUE,FEEDBACK,GROWTH_OPPORTUNITY,LEVEL - comments, comment authors, and comment timestamps
Dashboard uses:
- goal progress by person, team, department, or period
- open vs draft goals
- overdue or low-progress goals
- growth goals linked to feedback or growth opportunities
- value-linked goal alignment
- goal update activity
Example prompts:
Find published goals for each direct report this quarter and return current score, key result status, and linked growth signals.
Find goals linked to this growth opportunity and summarize whether the person has a concrete development plan.
Meetings, 1:1s, Agendas, Notes, and Actions
Use this domain to understand collaboration cadence and follow-through.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
findMeetings | Read | Meetings for the current user in a date range, with attendees, time, type, location, cancellation state, agenda items |
getMeetingDetails | Read | Full meeting details, attendees, agenda items, notes, actions, assignees, due dates |
scheduleMeeting | Write | Schedule a meeting or 1:1 |
addMeetingAgendaItem | Write | Add an agenda item |
addMeetingActionItem | Write | Add an action item |
addMeetingNote | Write | Add a meeting note |
Useful data points:
- meeting ID or
meetingRef - parent event ID for recurring meetings
- summary
- type:
MEETING,ONE_TO_ONE - location
- start time, end time, all-day flag, time zone
- cancellation state
- recurrence rule
- attendees and declined flags
- agenda items, evidence links, crossed state
- notes, authors, private note flag, timestamps
- action items, status, due date, primary and additional assignees
Dashboard uses:
- 1:1 cadence by manager-report pair
- meeting frequency and cancellation patterns
- agenda usage
- action assignment and completion follow-through
- open action workload
- evidence-backed meeting prep
Example prompts:
Find my 1:1s for the next two weeks, then load details for each and identify missing agendas or overdue action items.
For this manager and report, find meetings from the last 90 days and summarize cadence, actions, and recurring topics.
Leadership Insights
Use this domain when you want pre-aggregated people analytics across a reporting line or owner-filtered population.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
getLeadershipInsights | Read | Sentiment scores, goal progress scores, platform activity counts, focus areas, value distribution |
findPeopleByInsightCriteria | Read | People matching threshold criteria such as low sentiment, low OKR score, few 1:1s, or low feedback volume |
Owner-only filters:
leaderUserIddepartmentIdroleIdaffiliationKeymemberAttributeKey
Supported time ranges:
- default: six months
- custom: provide both
startDateandendDate
getLeadershipInsights sections:
sentiment_scoresgoal_progressplatform_activityfocus_areasvalue_distribution
Insight criteria signals:
SENTIMENT_SCOREOKR_SCOREFEEDBACKS_RECEIVEDFEEDBACKS_GIVENFEEDBACKS_GIVEN_WITH_GROWTH_OPPORTUNITIESONE_TO_ONESCOMPLETED_ACTIONS_PERCENTAGECURRENT_LEVELPROMOTIONS
Criteria comparisons:
EQGTGELTLE
Platform activity metric types can include:
FEEDBACKSFEEDBACK_REQUESTSMEETINGSMEETING_AGENDASMEETING_NOTESMEETING_ACTIONSCOMPLETED_ACTIONSGOALS_UPDATEDSURVEY_RESPONSESCONTEXTSNOTESSTRENGTHSGROWTH_OPPORTUNITIESFOCUS_AREASCOMMENTSREVIEW_RESPONSESAI_CHAT_CONVERSATIONS
Dashboard uses:
- team sentiment distribution
- low goal-progress watchlist
- engagement/activity dashboard
- focus-area heatmap
- values recognition map
- threshold-based people segments
- manager operating review dashboards
Example prompts:
Call getLeadershipInsights for my reporting line with sentiment_scores, goal_progress, platform_activity, focus_areas, and value_distribution for the last six months.
Find people with SENTIMENT_SCORE LT 4 and OKR_SCORE LT 5 in the last quarter. Return their department, role, level, and latest growth signals.
Surveys
Use this domain to analyze survey participation and question-level insights.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
findSurveys | Read | Surveys owned or led by the current user, including available survey runs and response rates |
getSurveyInsights | Read | Survey metadata, selected runs, response summary, questions, answer option counts, sentiment scores, themes |
Useful data points:
- survey ID and title
- trigger type
- status
- anonymity mode
- start time
- owner and leader IDs
- survey run IDs
- run started time
- recipient count
- responded recipient count
- response rate
- question ID, text, type
- option ID, label, value
- total responses by question and run
- sentiment score and sentiment response count
- themes
- option response totals
Survey run selection:
- If
surveyRunIdsis omitted,getSurveyInsightsuses the latest 10 runs. - A request can select at most 10 runs.
Survey question types:
ENPSFREE_TEXTINFOLIKERTMULTI_SELECTSINGLE_SELECTSTAR_RATINGYES_NO
Survey statuses:
DRAFTACTIVEWINDING_DOWNRETIREDCANCELED
Anonymity modes:
ANONYMOUSIDENTITY_OPTIONALIDENTITY_REQUIRED
Dashboard uses:
- response rate by survey and run
- question-level trends over time
- sentiment by question
- theme frequency
- option distribution charts
- onboarding/offboarding pulse analysis
- department or leader scoped survey dashboards, where permitted
Example prompts:
Find surveys I own or lead, then get insights for the latest runs of the engagement survey and summarize response rate, sentiment, and top themes.
For this survey, compare the last 6 runs question by question. Show sentiment movement and option distribution changes.
Career Framework
Use this domain to connect people analytics to role expectations.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
getCareerFramework | Read | Published framework, departments, roles, tracks, levels, overviews |
getLevelDetails | Read | Responsibilities, competencies, skills, and behaviors for one level |
Useful data points:
- framework ID and name
- department ID, name, overview, privacy flag
- role ID, name, overview, privacy flag
- track ID, name, overview, privacy flag
- level ID, name, sequence, overview, privacy flag
- responsibilities
- competencies
- skills
- behaviors
Dashboard uses:
- growth readiness by level
- competency gap analysis
- role expectation summaries
- promotion or progression prep
- mapping feedback themes to competency expectations
Example prompts:
Load this person's level details, then compare their growth signals against the competencies and behaviors expected at that level.
Values
Use this domain to understand the published company value taxonomy and connect it to feedback.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
listCompanyValues | Read | Published company values and descriptions |
Useful data points:
- value ID
- value name
- value description
Dashboard uses:
- values recognition distribution
- underrepresented values
- value-linked feedback trends
- value-linked goal alignment
Example prompts:
List company values, then compare them with value tags returned from feedback and leadership value distribution.
Work Context
Use this domain to connect development conversations to actual work evidence.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
getWorkSummary | Read | Recent context items for a person, optionally narrowed by collaborators and keyword |
Useful data points:
- context ID
- link
- metadata
- created and updated timestamps
- related user and collaborator scope from the request
Dashboard uses:
- evidence-backed feedback prep
- self-assessment evidence gathering
- collaboration context by person or pair
- work-context volume over time
Example prompts:
Get work summary for this person with this collaborator and use it as evidence for 1:1 prep.
Notes
Use this domain for personal ClarityLoop notes. These are separate from meeting notes.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
searchNotes | Read | Personal notes by title/content keyword or collection |
saveNote | Write | Create or update a personal note |
Useful data points:
- note ID
- title
- description/content
- collection ID
- evidence contexts
- created and updated timestamps
Dashboard uses:
- personal evidence log
- prep material search
- reflection history
Example prompts:
Search my notes for promotion evidence and group the results by theme.
Knowledge Search
Use this domain to retrieve ClarityLoop product documentation and people-science guidance.
Available tools:
| Tool | Mode | What it exposes |
|---|---|---|
searchKnowledge | Read | Product docs and people science search results with content snippets, title, path, category, authors, publication date, score |
Sources:
docsscienceboth
Dashboard uses:
- explain metric methodology alongside a dashboard
- retrieve people-development guidance for an insight
- product help in an assistant workflow
Example prompts:
Search science for feedback quality and use the results to explain how to interpret feedback sentiment.
Metric Recipes
Use these as starting points for external analytics.
| Metric | Tools | Calculation |
|---|---|---|
| Active headcount | searchPeople | Count active members, grouped by department, role, level, affiliation, or member attribute |
| Manager span | getDirectReports | Count reports for each manager |
| Feedback received | findReceivedFeedback or getGrowthSignals | Count shared feedback received by person and period |
| Feedback given | findGivenFeedback or getGrowthSignals | Count feedback given by current user or by available person scope |
| Feedback request response rate | findIncomingFeedbackRequests, findSentFeedbackRequests | responseCount / recipient count by request |
| Sentiment | getGrowthSignals, getLeadershipInsights | Use returned sentiment score fields by person and period |
| Goal progress | findGoals, getGoalDetails, getLeadershipInsights | Use currentScore or leadership goalProgress.score |
| Goal coverage | findGoals | Count people with at least one published goal in a period |
| 1:1 cadence | findMeetings | Count ONE_TO_ONE meetings by manager-report pair and period |
| Action follow-through | getMeetingDetails | Count completed vs open actions by assignee and due date |
| Survey response rate | findSurveys, getSurveyInsights | Use returned responseRate or respondedRecipients / totalRecipients |
| Survey sentiment | getSurveyInsights | Use question/run-level sentimentScore |
| Value distribution | getLeadershipInsights, findReceivedFeedback | Count value-tagged feedback or use returned value distribution |
| Focus area volume | getLeadershipInsights | Use feedbackCount, commentCount, and eventCount on focus areas |
| Growth theme frequency | getGrowthSignals, findReceivedFeedback | Count returned growth area IDs/titles over a period |
Suggested Data Model
For a reporting database, normalize MCP responses into these tables or equivalent warehouse models:
| Table | Primary key | Source tools |
|---|---|---|
people | user_id | getCurrentUser, searchPeople, getDirectReports |
people_attributes | user_id, attribute_id, value_key | searchPeople, getPeopleFilterOptions |
reporting_edges | manager_user_id, report_user_id | getDirectReports |
feedback | feedback_id | findReceivedFeedback, findGivenFeedback, getFeedbackDetails |
feedback_requests | feedback_request_id | findIncomingFeedbackRequests, findSentFeedbackRequests |
growth_signals | user_id, signal_type, signal_id, snapshot_at | getGrowthSignals |
goals | goal_id | findGoals, getGoalDetails |
goal_items | key_result_id | findGoals, getGoalDetails |
meetings | meeting_ref or meeting_id | findMeetings, getMeetingDetails |
meeting_actions | action_id | getMeetingDetails |
survey_runs | survey_run_id | findSurveys, getSurveyInsights |
survey_question_insights | survey_id, survey_run_id, question_id | getSurveyInsights |
values | value_id | listCompanyValues, getLeadershipInsights |
career_levels | level_id | getCareerFramework, getLevelDetails |
work_contexts | context_id | getWorkSummary |
notes | note_id | searchNotes |
Add these metadata fields to every ingested row:
source_toolextracted_atrequested_by_user_idworkspace_id, when available- original request filters
Prompt Templates for Clients
Build a Team Health Snapshot
Start with getCurrentUser. If I am a manager, use getDirectReports for my team. For each direct report, get growth signals for the last 90 days and find published goals for the same period. Return a dashboard-ready JSON object with person, level, sentiment, feedback counts, top strengths, top growth areas, goal count, and average goal score.
Build a Leadership Operating Review
Use getLeadershipInsights for the last 6 months. Include sentiment_scores, goal_progress, platform_activity, focus_areas, and value_distribution. Then use findPeopleByInsightCriteria to identify people with SENTIMENT_SCORE LT 4 or OKR_SCORE LT 5. Return charts to build, source tool names, and the exact fields to use.
Build Survey Trend Analysis
Use findSurveys to locate the survey by title. Use getSurveyInsights for the latest 10 runs. Create a run-by-question table with total responses, sentiment score, themes, and option distributions. Flag questions where sentiment declined across runs.
Build 1:1 Follow-Through Reporting
Use findMeetings for the last 90 days. Filter to ONE_TO_ONE meetings. For each meeting, use getMeetingDetails. Build metrics for meeting cadence, agenda item count, open action count, completed action count, overdue actions, and assignee workload.
Build Evidence-Backed Review Prep
Use searchPeople to resolve the person. Use findReceivedFeedback, getGrowthSignals, findGoals, getWorkSummary, and searchNotes for the review period. Summarize evidence by strengths, growth areas, values, goals, and work context links.
Practical Limits
- MCP is optimized for governed, scoped access from AI clients, not unrestricted historical export.
- Most paged tools cap
pageSizeat 20. getSurveyInsightsreturns at most 10 selected survey runs.findMeetingsshould be queried in date windows, with a maximum range of 45 days at a time.- Some tools return less data depending on the authenticated user's role, manager relationships, survey ownership, and product permissions.
- Sensitive member attributes can be identified by the
attributeSensitiveorsensitivefields and should be handled carefully in downstream systems.
Write Tools and Agent Safety
The following tools can modify ClarityLoop data:
giveFeedbackrequestFeedbackcreateGoaladdGoalItemlinkToGoalupdateGoalProgressscheduleMeetingaddMeetingAgendaItemaddMeetingActionItemaddMeetingNotesaveNote
Recommended client behavior:
- Show the exact proposed change before calling a write tool.
- Ask the user to confirm recipients, dates, visibility, and sharing settings.
- Prefer drafts where the tool supports draft state.
- Include source evidence links when creating feedback, agenda items, notes, or goals from work context.
- Store returned IDs so follow-up actions can reference the created record.