MCP Integration Guide
How to build AI-powered CRM features using the Model Context Protocol (MCP) — tools, resources, prompts, orchestrations, and predictive models.
MCP Integration Guide
The Model Context Protocol (MCP) is the standard interface between AI models and HotCRM's business data. MCP enables AI agents to search records, read pipeline data, analyze deals, and take actions — all through a structured, type-safe protocol.
HotCRM implements three MCP primitives plus higher-level AI capabilities:
| Primitive | Purpose | Example |
|---|---|---|
| Tools | Actions the AI can perform | Search accounts, update deal stage |
| Resources | Read-only data the AI can access | Pipeline summary, forecast data |
| Prompts | Pre-built prompt templates | Deal analysis, win/loss review |
| Orchestrations | Multi-step AI pipelines | Sales intelligence workflow |
| Predictive Models | ML model definitions | Lead scoring, churn prediction |
Why MCP for CRM?
Traditional CRM integrations require custom API code for every AI feature. MCP provides a universal protocol that any AI model can use:
- Structured tool calling: AI models invoke CRM operations through typed schemas, not free-form API calls
- Context injection: Resources give AI models real-time access to pipeline, forecast, and territory data
- Reusable prompts: Pre-built templates encode domain expertise (sales methodology, support playbooks)
- Composability: Tools, resources, and prompts combine into orchestrations for complex workflows
MCP Tools
Tools are operations that AI agents can invoke. Each tool has a name, description, and a JSON Schema defining its input parameters.
Defining a Tool
import { MCPToolSchema } from '@objectstack/spec/ai';
export const SearchAccountsTool = MCPToolSchema.parse({
name: 'search_accounts',
description: 'Search CRM accounts by name, industry, or revenue range',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string', description: 'Search term for account name' },
industry: { type: 'string', description: 'Filter by industry vertical' },
minRevenue: { type: 'number', description: 'Minimum annual revenue threshold' },
},
required: ['query']
}
});CRM Tool Catalog
HotCRM ships 24 MCP tools across all clouds:
| Cloud | Tool | Description |
|---|---|---|
| Sales | search_accounts | Search accounts by name, industry, or revenue |
| Sales | get_opportunity | Retrieve full opportunity details |
| Sales | update_deal_stage | Move an opportunity between pipeline stages |
| Sales | create_activity | Log a call, email, meeting, or task |
| Finance | create_invoice | Generate an invoice from a contract |
| Finance | record_payment | Record a payment against an invoice |
| Support | search_cases | Find support cases by status or priority |
| Support | escalate_case | Escalate a case to a higher tier |
| Marketing | create_campaign | Set up a new marketing campaign |
| Marketing | add_campaign_members | Add leads/contacts to a campaign |
| Products | search_products | Search the product catalog |
| Products | generate_quote | Generate a quote with pricing rules |
| HR | search_employees | Find employees by department or role |
| HR | create_job_requisition | Open a new hiring requisition |
Tool Implementation Pattern
Tools follow a two-file pattern: schema definition (.mcp.ts) and handler (.action.ts):
packages/crm/src/
├── crm_mcp_tools.mcp.ts # Tool schemas (what the AI sees)
├── actions/
│ ├── ai_smart_briefing.action.ts # Tool handler (what runs)
│ └── deal_copilot.action.tsThe .mcp.ts file defines the contract; the .action.ts file implements the business logic using ObjectQL:
// In the action handler — always use ObjectQL, never raw SQL
const accounts = await broker.find('account', {
filters: [
['name', 'contains', query],
['industry', '=', industry]
],
fields: ['name', 'industry', 'annual_revenue', 'owner'],
limit: 20
});MCP Resources
Resources expose read-only data to AI models for context. Unlike tools, resources are passive — they provide information the AI can reference when generating responses.
Defining a Resource
import { MCPResourceSchema } from '@objectstack/spec/ai';
export const PipelineSummaryResource = MCPResourceSchema.parse({
uri: 'hotcrm://crm/pipeline-summary',
name: 'Pipeline Summary',
description: 'Current sales pipeline with stage distribution and velocity metrics',
mimeType: 'application/json'
});CRM Resource Catalog
| Cloud | Resource | URI | Description |
|---|---|---|---|
| Sales | Account List | hotcrm://crm/accounts | Paginated accounts with health scores |
| Sales | Pipeline Summary | hotcrm://crm/pipeline-summary | Stage distribution and velocity |
| Sales | Forecast Data | hotcrm://crm/forecast | Revenue forecasts by period/segment |
| Sales | Territory Map | hotcrm://crm/territories | Territory assignments and quotas |
| Support | Case Queue | hotcrm://support/case-queue | Open cases by priority and SLA status |
| Support | Knowledge Base | hotcrm://support/knowledge | Article summaries for case resolution |
| Finance | AR Aging | hotcrm://finance/ar-aging | Accounts receivable aging summary |
| HR | Org Chart | hotcrm://hr/org-chart | Department structure and headcount |
Resource URI Convention
All HotCRM resources use the hotcrm:// URI scheme:
hotcrm://{cloud}/{resource-name}Examples:
hotcrm://crm/pipeline-summaryhotcrm://support/case-queuehotcrm://finance/ar-aging
MCP Prompts
Prompts are pre-built templates that encode domain expertise. They accept arguments and generate structured prompts for AI models.
Defining a Prompt
import { MCPPromptSchema } from '@objectstack/spec/ai';
export const DealAnalysisPrompt = MCPPromptSchema.parse({
name: 'deal_analysis',
description: 'Analyze deal health with risk assessment and close probability',
arguments: [
{
name: 'opportunity_id',
description: 'The opportunity record to analyze',
required: true
}
]
});Prompt Catalog by Cloud
Sales Prompts (crm_prompts.mcp.ts):
| Prompt | Purpose |
|---|---|
deal_analysis | Risk assessment and close probability for an opportunity |
customer_360_summary | Holistic account view across all touchpoints |
next_best_action | Recommend the optimal next step for a deal |
win_loss_analysis | Extract learnings from closed won/lost deals |
Support Prompts (support_prompts.mcp.ts):
| Prompt | Purpose |
|---|---|
case_resolution | Suggest resolution steps based on case history |
escalation_analysis | Determine if a case needs escalation |
customer_sentiment | Analyze sentiment from case communications |
HR Prompts (hr_prompts.mcp.ts):
| Prompt | Purpose |
|---|---|
candidate_evaluation | Evaluate candidate fit against job requirements |
employee_development | Suggest development plans based on performance |
retention_risk | Assess employee flight risk and recommend actions |
AI Orchestrations
Orchestrations chain multiple AI tasks into multi-step pipelines triggered by business events. Each step can use different models, and results flow between steps.
Defining an Orchestration
import { AIOrchestrationSchema } from '@objectstack/spec/ai';
export const SalesOrchestration = AIOrchestrationSchema.parse({
name: 'sales_deal_pipeline',
label: 'Sales Deal Intelligence Pipeline',
description: 'Multi-step AI analysis triggered when an opportunity changes stage',
trigger: {
type: 'record_change',
object: 'opportunity',
field: 'stage'
},
steps: [
{
id: 'classify_risk',
type: 'ai_task',
model: 'gpt-4o',
prompt: 'Classify this deal risk as low, medium, or high based on: {{deal_summary}}',
outputVariable: 'risk_level'
},
{
id: 'summarize_deal',
type: 'ai_task',
model: 'gpt-4o',
prompt: 'Generate a 3-sentence executive summary for: {{opportunity.name}}',
outputVariable: 'deal_summary_text'
},
{
id: 'recommend_action',
type: 'ai_task',
model: 'gpt-4o',
prompt: 'Based on risk={{risk_level}}, recommend the single best next action',
outputVariable: 'recommended_action'
}
],
postActions: [
{
type: 'fieldUpdate',
object: 'opportunity',
field: 'risk_level',
value: '{{classify_risk.output}}'
},
{
type: 'emailAlert',
condition: "risk_level = 'high'",
template: 'high_risk_deal_alert',
recipients: ['${opportunity.owner.email}', '${opportunity.owner.manager.email}']
}
],
execution: {
mode: 'sequential',
timeoutSeconds: 120
}
});Available Orchestrations
| Orchestration | Trigger | Steps | Cloud |
|---|---|---|---|
| Sales Deal Pipeline | Opportunity stage change | Risk classify → Summarize → Recommend | Sales |
| Support Triage Pipeline | New case created | Categorize → Sentiment → Suggest resolution → Draft response | Support |
Files:
packages/ai/src/sales_orchestration.orchestration.ts,packages/ai/src/support_orchestration.orchestration.ts
Predictive Models
Predictive models define machine learning configurations for scoring, classification, and forecasting. The metadata describes features, training parameters, and deployment settings — the runtime handles model training and inference.
Defining a Predictive Model
import { PredictiveModelSchema } from '@objectstack/spec/ai';
export const LeadScoringModel = PredictiveModelSchema.parse({
name: 'lead_scoring',
label: 'Lead Conversion Predictor',
description: 'Gradient-boosting classifier predicting lead-to-opportunity conversion',
object: 'lead',
target: {
field: 'is_converted',
type: 'binary_classification'
},
features: [
{ field: 'industry', type: 'categorical' },
{ field: 'company_size', type: 'numerical' },
{ field: 'lead_source', type: 'categorical' },
{ field: 'engagement_score', type: 'numerical' },
{ field: 'email_opens', type: 'numerical' },
{ field: 'website_visits', type: 'numerical' },
],
training: {
algorithm: 'gradient_boosting',
splitRatio: { train: 0.7, validation: 0.15, test: 0.15 },
crossValidation: { folds: 5 },
minRecords: 5000
}
});Model Catalog
| Model | Object | Type | Key Features |
|---|---|---|---|
| Lead Scoring | lead | Binary classification | Industry, company size, engagement, email opens, website visits |
| Churn Prediction | account | Binary classification | Activity recency, support tickets, satisfaction, contract end, usage trend |
| Deal Forecast | opportunity | Binary classification | Stage, amount, days in stage, activity count, competitors, discount |
Files:
packages/ai/src/lead_scoring.predictive.ts,packages/ai/src/churn_prediction.predictive.ts,packages/ai/src/deal_forecast.predictive.ts
Putting It All Together
A complete AI-powered CRM workflow combines all MCP primitives:
- Resource provides context: Pipeline summary + account data
- Prompt structures the request: "Analyze this deal's risk"
- Tool takes action: Update the deal stage, log an activity
- Orchestration chains steps: Classify → Summarize → Recommend → Notify
- Predictive Model scores records: Lead conversion probability
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Resources │────▶│ AI Agent │────▶│ Tools │
│ (read data) │ │ (reasoning) │ │ (take action)│
└─────────────┘ └──────┬───────┘ └─────────────┘
│
┌──────▼───────┐
│ Prompts │
│ (templates) │
└──────────────┘File Organization
All MCP metadata lives alongside the business objects it serves:
packages/crm/src/
├── account.object.ts # Data model
├── crm_mcp_tools.mcp.ts # MCP tools (search, update, create)
├── crm_mcp_resources.mcp.ts # MCP resources (pipeline, forecast)
├── crm_prompts.mcp.ts # MCP prompts (deal analysis, next action)
├── actions/
│ ├── ai_smart_briefing.action.ts # Tool handler
│ └── deal_copilot.action.ts # Tool handler
packages/ai/src/
├── sales_orchestration.orchestration.ts # Multi-step pipeline
├── lead_scoring.predictive.ts # ML model definition
├── churn_prediction.predictive.ts # ML model definition
└── deal_forecast.predictive.ts # ML model definitionNext steps: See the Metadata Types Reference for the complete catalog of all HotCRM metadata types.