Skip to main content

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/mcp
  • https://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. Use searchPeople or getCurrentUser to resolve it.
  • fromDate, toDate, startDate, endDate: date strings in YYYY-MM-DD format 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 by findMeetings. Pass it back to meeting detail and write tools.

For analytics, use a staged extraction pattern:

  1. Call getCurrentUser to identify the user, workspace, role, level, affiliations, and available scope.
  2. Call getPeopleFilterOptions to load reusable dimensions such as departments, roles, levels, affiliations, and member attributes.
  3. Call searchPeople or getDirectReports to build the people population for the analysis.
  4. Pull the relevant signal families: feedback, goals, meetings, surveys, work context, values, career framework, and leadership insights.
  5. Store normalized snapshots in your own analytics system with timestamps and source tool names.
  6. Build derived metrics from stable IDs, dates, counts, statuses, and score fields.

For conversational agents, use a narrower pattern:

  1. Start with getCurrentUser.
  2. Resolve people with searchPeople.
  3. Load the few records needed for the task.
  4. 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:

ToolModeWhat it exposes
getCurrentUserReadCurrent user, workspace, title, level, affiliations, member attributes, workspace role
getPeopleFilterOptionsReadCareer framework summary, departments, roles, levels, affiliations, member attribute options, workspace search filters
searchPeopleReadWorkspace members with profile, title, level, affiliations, attributes, active/current status, role
getDirectReportsReadManager-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:

ToolModeWhat it exposes
findReceivedFeedbackReadFeedback received by a person, with sender, summary, sentiment, status, request ID, sharing flags, linked values, strengths, growth opportunities, timestamps
findGivenFeedbackReadFeedback given by the current user, with recipient, summary, sentiment, status, linked values, strengths, growth opportunities, timestamps
findIncomingFeedbackRequestsReadFeedback requests assigned to the current user, request subject, recipients, response status/counts, timestamps
findSentFeedbackRequestsReadFeedback requests sent by the current user for a person, recipients, response status/counts, manager mode, timestamps
getFeedbackDetailsReadFull feedback body, description, SBI/SSC/STAR structures, linked values, linked strengths, linked growth opportunities, evidence contexts
getGrowthSignalsReadStrengths, growth areas, linked values, sentiment scores, feedback given/received counts for a person
giveFeedbackWriteCreate/update draft feedback or share feedback
requestFeedbackWriteSend 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:

ToolModeWhat it exposes
findGoalsReadOne person's goals, key results/actions, statuses, dates, scores, links, owner
getGoalDetailsReadFull goal or key result/action details, comments, source links and metadata
createGoalWriteCreate a draft or published goal
addGoalItemWriteAdd a key result/action to a goal
linkToGoalWriteLink values, feedback, growth opportunities, or levels to a goal
updateGoalProgressWriteUpdate 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:

ToolModeWhat it exposes
findMeetingsReadMeetings for the current user in a date range, with attendees, time, type, location, cancellation state, agenda items
getMeetingDetailsReadFull meeting details, attendees, agenda items, notes, actions, assignees, due dates
scheduleMeetingWriteSchedule a meeting or 1:1
addMeetingAgendaItemWriteAdd an agenda item
addMeetingActionItemWriteAdd an action item
addMeetingNoteWriteAdd 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:

ToolModeWhat it exposes
getLeadershipInsightsReadSentiment scores, goal progress scores, platform activity counts, focus areas, value distribution
findPeopleByInsightCriteriaReadPeople matching threshold criteria such as low sentiment, low OKR score, few 1:1s, or low feedback volume

Owner-only filters:

  • leaderUserId
  • departmentId
  • roleId
  • affiliationKey
  • memberAttributeKey

Supported time ranges:

  • default: six months
  • custom: provide both startDate and endDate

getLeadershipInsights sections:

  • sentiment_scores
  • goal_progress
  • platform_activity
  • focus_areas
  • value_distribution

Insight criteria signals:

  • SENTIMENT_SCORE
  • OKR_SCORE
  • FEEDBACKS_RECEIVED
  • FEEDBACKS_GIVEN
  • FEEDBACKS_GIVEN_WITH_GROWTH_OPPORTUNITIES
  • ONE_TO_ONES
  • COMPLETED_ACTIONS_PERCENTAGE
  • CURRENT_LEVEL
  • PROMOTIONS

Criteria comparisons:

  • EQ
  • GT
  • GE
  • LT
  • LE

Platform activity metric types can include:

  • FEEDBACKS
  • FEEDBACK_REQUESTS
  • MEETINGS
  • MEETING_AGENDAS
  • MEETING_NOTES
  • MEETING_ACTIONS
  • COMPLETED_ACTIONS
  • GOALS_UPDATED
  • SURVEY_RESPONSES
  • CONTEXTS
  • NOTES
  • STRENGTHS
  • GROWTH_OPPORTUNITIES
  • FOCUS_AREAS
  • COMMENTS
  • REVIEW_RESPONSES
  • AI_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:

ToolModeWhat it exposes
findSurveysReadSurveys owned or led by the current user, including available survey runs and response rates
getSurveyInsightsReadSurvey 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 surveyRunIds is omitted, getSurveyInsights uses the latest 10 runs.
  • A request can select at most 10 runs.

Survey question types:

  • ENPS
  • FREE_TEXT
  • INFO
  • LIKERT
  • MULTI_SELECT
  • SINGLE_SELECT
  • STAR_RATING
  • YES_NO

Survey statuses:

  • DRAFT
  • ACTIVE
  • WINDING_DOWN
  • RETIRED
  • CANCELED

Anonymity modes:

  • ANONYMOUS
  • IDENTITY_OPTIONAL
  • IDENTITY_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:

ToolModeWhat it exposes
getCareerFrameworkReadPublished framework, departments, roles, tracks, levels, overviews
getLevelDetailsReadResponsibilities, 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:

ToolModeWhat it exposes
listCompanyValuesReadPublished 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:

ToolModeWhat it exposes
getWorkSummaryReadRecent 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:

ToolModeWhat it exposes
searchNotesReadPersonal notes by title/content keyword or collection
saveNoteWriteCreate 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.

Use this domain to retrieve ClarityLoop product documentation and people-science guidance.

Available tools:

ToolModeWhat it exposes
searchKnowledgeReadProduct docs and people science search results with content snippets, title, path, category, authors, publication date, score

Sources:

  • docs
  • science
  • both

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.

MetricToolsCalculation
Active headcountsearchPeopleCount active members, grouped by department, role, level, affiliation, or member attribute
Manager spangetDirectReportsCount reports for each manager
Feedback receivedfindReceivedFeedback or getGrowthSignalsCount shared feedback received by person and period
Feedback givenfindGivenFeedback or getGrowthSignalsCount feedback given by current user or by available person scope
Feedback request response ratefindIncomingFeedbackRequests, findSentFeedbackRequestsresponseCount / recipient count by request
SentimentgetGrowthSignals, getLeadershipInsightsUse returned sentiment score fields by person and period
Goal progressfindGoals, getGoalDetails, getLeadershipInsightsUse currentScore or leadership goalProgress.score
Goal coveragefindGoalsCount people with at least one published goal in a period
1:1 cadencefindMeetingsCount ONE_TO_ONE meetings by manager-report pair and period
Action follow-throughgetMeetingDetailsCount completed vs open actions by assignee and due date
Survey response ratefindSurveys, getSurveyInsightsUse returned responseRate or respondedRecipients / totalRecipients
Survey sentimentgetSurveyInsightsUse question/run-level sentimentScore
Value distributiongetLeadershipInsights, findReceivedFeedbackCount value-tagged feedback or use returned value distribution
Focus area volumegetLeadershipInsightsUse feedbackCount, commentCount, and eventCount on focus areas
Growth theme frequencygetGrowthSignals, findReceivedFeedbackCount 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:

TablePrimary keySource tools
peopleuser_idgetCurrentUser, searchPeople, getDirectReports
people_attributesuser_id, attribute_id, value_keysearchPeople, getPeopleFilterOptions
reporting_edgesmanager_user_id, report_user_idgetDirectReports
feedbackfeedback_idfindReceivedFeedback, findGivenFeedback, getFeedbackDetails
feedback_requestsfeedback_request_idfindIncomingFeedbackRequests, findSentFeedbackRequests
growth_signalsuser_id, signal_type, signal_id, snapshot_atgetGrowthSignals
goalsgoal_idfindGoals, getGoalDetails
goal_itemskey_result_idfindGoals, getGoalDetails
meetingsmeeting_ref or meeting_idfindMeetings, getMeetingDetails
meeting_actionsaction_idgetMeetingDetails
survey_runssurvey_run_idfindSurveys, getSurveyInsights
survey_question_insightssurvey_id, survey_run_id, question_idgetSurveyInsights
valuesvalue_idlistCompanyValues, getLeadershipInsights
career_levelslevel_idgetCareerFramework, getLevelDetails
work_contextscontext_idgetWorkSummary
notesnote_idsearchNotes

Add these metadata fields to every ingested row:

  • source_tool
  • extracted_at
  • requested_by_user_id
  • workspace_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 pageSize at 20.
  • getSurveyInsights returns at most 10 selected survey runs.
  • findMeetings should 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 attributeSensitive or sensitive fields and should be handled carefully in downstream systems.

Write Tools and Agent Safety​

The following tools can modify ClarityLoop data:

  • giveFeedback
  • requestFeedback
  • createGoal
  • addGoalItem
  • linkToGoal
  • updateGoalProgress
  • scheduleMeeting
  • addMeetingAgendaItem
  • addMeetingActionItem
  • addMeetingNote
  • saveNote

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.