Skip to main content
The Convosphere MCP server exposes Convosphere product APIs as callable tools for AI clients such as Cursor. Tools run with the authenticated user’s OAuth context and, when available, are tracked against the user’s default MCP API key.

​
Tool access model

MCP tools use two layers of authorization:
  1. MCP authentication verifies the Cursor OAuth access token.
  2. Application authorization checks user role, plan, ownership, and route-level permissions.
This means a tool can be connected correctly but still return 403 when the current user is not allowed to perform the action. For example, canCreateAgent can return limitReached on a free plan after the user already has one agent.

​
Core tools

These tools are always available and are the best first tests after connecting.
ToolPurpose
whoAmIReturns the authenticated user ID, role, plan, tenant, tracking status, and auth kind.
getSessionContextLists available tool categories and server capabilities.
loadToolsForTaskFinds relevant tools for a natural-language task.
Example: 
Use convosphereMcp whoAmI

​
Health and diagnostics

ToolPurpose
healthCheckChecks application, database, and Redis health.
dbHealthCheckChecks database and Redis connectivity.
getUsageMetricsReturns usage totals and plan credits for the current user.
getUsageHistoryReturns daily usage history.

​
User and account tools

ToolPurpose
getUserProfileReads the current user’s profile by ID.
getUserPreferencesReads dashboard/application preferences.
getUserThemeReads theme settings.
getSocketTokenGenerates a short-lived WebSocket token for the authenticated user.
Mutation tools such as updateUserProfile, updateUserPreferences, updateUserTheme, changePassword, and deleteUserAccount should only be tested with a test account.

​
Agents and analytics

ToolPurpose
canCreateAgentChecks whether the user’s plan allows another agent.
getAgentReads an agent owned by the user.
getAgentSettingsReads widget and agent settings.
getAgentAnalyticsReads analytics for an agent and time range.
Example: 
Use convosphereMcp getAgentAnalytics with id "<agent-id>" and range "30d"

​
Conversations and messages

ToolPurpose
listDashboardConversationsLists dashboard-visible conversations for an agent.
listConversationsLists public/API conversations for an agent.
getDashboardConversationReads messages for a dashboard conversation thread.
getConversationReads messages for a public/API conversation thread.
listAgentMessagesLists agent messages where available.
getChatSuggestionsGenerates follow-up suggestions from conversation context.
Conversation detail tools require both id and threadId.

​
Knowledge, training, and Notion

ToolPurpose
listKnowledgeDocumentsLists documents connected to an agent knowledge base.
previewKnowledgeDocumentPreviews a specific knowledge document.
listTrainingDocumentsLists training documents for an agent.
listFineTuningJobsLists fine-tuning jobs for an agent.
listNotionConnectionsLists Notion connections for an agent.
listNotionPagesLists pages for a Notion connection.
listNotionDatabasesLists databases for a Notion connection.
Tools that upload files, add URLs, add Q&A, sync Notion, reindex data, or start fine-tuning can change data or start background jobs. Test them with disposable data.

​
Tickets and notifications

ToolPurpose
listTicketsLists tickets for the authenticated user.
getTicketReads a specific ticket.
listCommentsLists comments for a ticket.
listNotificationsLists notifications.
getUnreadCountReturns unread notification count.
Create, update, delete, mark-read, and bulk notification tools mutate data.

​
Integrations and providers

ToolPurpose
listProvidersLists available integration providers.
listIntegrationsLists integrations owned by the user.
getIntegrationReads a specific integration.
getOAuthAuthUrlBuilds an OAuth authorization URL for an integration provider.
testIntegrationTests an existing integration connection.
Creating, updating, deleting, OAuth callbacks, and webhook handlers can create or modify integration records.

​
Public and pricing tools

ToolPurpose
getPublicWidgetSettingsReads public widget settings for an agent.
getPublicIntelligentBotReads the public intelligent bot configuration.
listBotTemplatesLists bot templates.
listStudentTemplatesLists student templates.
getQuickStartOptionsReads quick-start progress.
getStudentPersonalizationReads onboarding personalization data.
listPlansLists available subscription plans.
listPricingPlansLists pricing plans.
calculatePricingEstimates pricing for agent/message requirements.
searchOrganizationsSearches organization records.

​
Admin-only tools

Some tools are exposed through MCP but still require admin permissions in the application layer. A normal user should expect 401 or 403 for these tools. Examples include:
  • getSchedule
  • listLeads
  • Admin analytics, user, ticket, pricing, configuration, and super-admin tools
Do not bypass these guards for normal MCP users.

​
Safe test checklist

Use this checklist after a new MCP connection:
1

Verify identity

Use convosphereMcp whoAmI
2

Verify server health

Use convosphereMcp healthCheck
3

Verify usage tracking

Use convosphereMcp getUsageMetrics
4

Verify user-scoped proxying

Use convosphereMcp getUserPreferences
5

Verify agent reads

Use convosphereMcp getAgent with id "<agent-id>"

​
Unsafe test categories

Do not run these on a real account unless the intent is explicit:
  • Account deletion and password changes
  • Create, update, and delete tools
  • Payment and Razorpay webhook tools
  • Webhook receiver tools
  • File upload and URL ingestion tools
  • Fine-tuning start tools
  • Notion sync tools
  • Ticket creation tools that notify users or admins
Use a test user, test agent, and disposable records for full end-to-end mutation testing.