MCP Tool Reference

Yaya Engine exposes two separate MCP servers with two separate trust models. YayaServer carries 3 tools reachable at /mcp/yaya behind the shared auth.admin_token middleware — this is the machine-to-machine surface Dify's AI agents call to read and update a user's actions [@yaya-server] [@ai-routes]. InternalYayaServer carries 20 tools reachable at /mcp/internal-yaya behind Passport OAuth (auth:api + can:mcp.access) — this is the operations surface the Atram team drives from Claude Desktop or Claude Code to search users, review alert delivery, approve or reject verification evidence, and inspect payouts and message batches [@internal-server] [@ai-routes]. Every internal tool extends InternalTool, which hides the tool from a caller whose AdminUser lacks the required Spatie permission and stamps a readOnlyHint or destructiveHint annotation depending on whether the tool writes [@internal-tool-base]. See MCP servers for how the two servers are wired into routing and MCP tools for the broader concept; see Add an MCP tool for the procedure to add a new one.

Permission model

InternalTool::eligibleForRegistration() requires the resolved AdminUser to hold mcp.access (AdminAccess::PERMISSION_MCP_ACCESS) plus whichever of mcp.tools.read or mcp.tools.write the tool declares as $requiredPermission [@internal-tool-base]. Every internal tool defaults to $isReadOnly = true and mcp.tools.read; only ApproveEvidenceTool and RejectEvidenceTool override both to false / mcp.tools.write [@approve-evidence] [@reject-evidence]. Three RBAC roles compose these two permissions: mcp_admin gets mcp.access + mcp.tools.read + mcp.tools.write; mcp_viewer gets mcp.access + mcp.tools.read only; manager gets the manager permissions plus mcp.access + mcp.tools.read [@admin-access]. YayaServer tools carry no such per-tool permission check — the whole server sits behind the single shared admin token, since its only caller is the Dify agent, not a human operator with a role [@ai-routes].

YayaServer — Dify agent tools

Mounted at /mcp/yaya behind auth.admin_token; the tools operate on a single user's actions and steps, with no admin-permission distinction between them [@yaya-server] [@ai-routes].

Tool	Read/Write	Entities touched
GetUserActionsTool	read	User, UserAction (with step counts) [@get-user-actions]
GetUserActionDetailsTool	read	UserAction, Action, UserActionStep [@get-user-action-details]
UpdateActionStepStatusTool	write	UserActionStep, delegates to UserActionService::completeStep [@update-action-step-status]

UpdateActionStepStatusTool is the only write path on this server. It looks up the step, calls UserActionService::completeStep($step, source: 'mcp_tool'), and surfaces any ValidationException as an MCP error rather than throwing — this is how the tool tells an agent "this step isn't completable yet" (for example, a step that still requires evidence) without crashing the agent session [@update-action-step-status].

InternalYayaServer — operations tools

Mounted at /mcp/internal-yaya behind Passport OAuth (auth:api + can:mcp.access); every row below additionally needs the listed mcp.tools.* permission per InternalTool::eligibleForRegistration() [@internal-server] [@internal-tool-base].

Users

Tool	Read/Write	Permission	Entities touched
SearchUsersTool	read	mcp.tools.read	User, Fsp — name/phone/FSP substring search [@search-users]
QueryUsersTool	read	mcp.tools.read	User, Fsp, primary location, via UserQueryService — filters on alert, severity, verified, onboarded, FSP; paginated [@query-users]
GetUserProfileTool	read	mcp.tools.read	User, Fsp, UserAction, UserAlert, Conversation, Message [@get-user-profile]
GetUserChannelAccountsTool	read	mcp.tools.read	User, ChannelAccount [@get-user-channel-accounts]
GetUserConversationsTool	read	mcp.tools.read	Conversation, Message (count + latest preview) [@get-user-conversations]
ReadConversationMessagesTool	read	mcp.tools.read	Conversation, Message [@read-conversation-messages]

QueryUsersTool and GetAlertUsersTool (below) share the same pagination contract: a limit/offset pair, a total_matching count distinct from the page's count, and a has_more/next_offset pair the tool's own description tells the calling agent to check before reporting totals [@query-users] [@get-alert-users]. GetUserProfileTool and GetUserChannelAccountsTool both reject a non-integer user_id outright instead of coercing it, on the reasoning that a malformed ID from an MCP client is an upstream bug worth surfacing rather than silently working around [@get-user-profile] [@get-user-channel-accounts].

Alerts

Tool	Read/Write	Permission	Entities touched
ListActiveAlertsTool	read	mcp.tools.read	Alert, UserAlert (assigned-count) [@list-active-alerts]
GetAlertsSummaryTool	read	mcp.tools.read	Alert, UserAlert — aggregated by severity/type over a date range [@get-alerts-summary]
GetAlertUsersTool	read	mcp.tools.read	Alert, via AlertDeliveryInsightsService::alertUsers — filterable by delivery status, verified, onboarded [@get-alert-users]
GetAlertDeliveryReportTool	read	mcp.tools.read	Alert, via AlertDeliveryInsightsService::deliveryReport — aggregates linked message batches [@get-alert-delivery-report]

Verifications

Tool	Read/Write	Permission	Entities touched
ListPendingVerificationsTool	read	mcp.tools.read	UserActionStep (status = evidence_uploaded), UserAction, User, Fsp [@list-pending-verifications]
GetVerificationDetailTool	read	mcp.tools.read	UserActionStep, UserAction, User, Fsp, AdminUser (approver/rejecter) [@get-verification-detail]
ApproveEvidenceTool	write	mcp.tools.write	UserActionStep, via UserActionService::approveEvidence [@approve-evidence]
RejectEvidenceTool	write	mcp.tools.write	UserActionStep, via UserActionService::rejectEvidence [@reject-evidence]

Both write tools guard on step status before calling the service: a step not currently in evidence_uploaded status is rejected with a message naming the actual and expected status, rather than silently no-oping [@approve-evidence] [@reject-evidence]. ApproveEvidenceTool's description notes that approving the last outstanding step on a UserAction can auto-complete the action and trigger a payout — the tool itself does not create the payout, UserActionService does [@approve-evidence]. RejectEvidenceTool requires a free-text reason and an optional category (image_unclear, wrong_evidence, fraud; defaults to wrong_evidence) drawn from RejectionReasonCategoryEnum [@reject-evidence].

Payouts

Tool	Read/Write	Permission	Entities touched
ListPendingPayoutsTool	read	mcp.tools.read	RequestedPayout, User, Fsp, UserAction — status-filterable, defaults to pending [@list-pending-payouts]

Messaging and batches

Tool	Read/Write	Permission	Entities touched
GetMessageDeliveryStatsTool	read	mcp.tools.read	via MessageAnalyticsService::statsForPeriod — channel/status/FSP breakdowns [@get-message-delivery-stats]
GetBatchStatusTool	read	mcp.tools.read	MessageBatch, Fsp — single batch, progress + success rate [@get-batch-status]
ListRecentBatchesTool	read	mcp.tools.read	MessageBatch, Fsp — status/FSP-filterable list [@list-recent-batches]

FSPs and operations

Tool	Read/Write	Permission	Entities touched
ListFspsTool	read	mcp.tools.read	Fsp (with user counts) [@list-fsps]
GetFspSummaryTool	read	mcp.tools.read	Fsp, User, UserAction, RequestedPayout — one FSP's users/actions/payouts/config status [@get-fsp-summary]
GetOperationsSummaryTool	read	mcp.tools.read	UserActionStep, RequestedPayout, User, Message, UserAction — queue depths + activity over days (default 1, max 30) [@get-operations-summary]

GetOperationsSummaryTool is the dashboard aggregate the server's instructions tell an agent to call first for a general overview before drilling into a specific user, alert, or verification queue [@internal-server] [@get-operations-summary].