Spotlight AI — MCP Integration Guide

Table of Contents

• Overview

• How It Works

• Tools

  • getDeal

  • searchMeetings

• Usage Patterns

• Priority Rules

• Troubleshooting

Overview

The Spotlight AI MCP server exposes deal and meeting intelligence from the Spotlight platform to AI assistants (Claude, GPT, etc.) via the Model Context Protocol (MCP). Once connected, the assistant can retrieve enriched deal data and meeting records on behalf of the user — without needing any custom integration code.

ℹ What is MCP? MCP (Model Context Protocol) is an open standard that allows AI assistants to call structured tools hosted on external servers. Your AI assistant calls the Spotlight MCP server just like any other MCP tool provider.

Available Tools

How It Works

You don't call the MCP tools directly — your AI assistant does. You interact naturally in chat, and the assistant decides when and how to call the tools.

Step 1 — You ask a natural language question

"What's the health of the Acme renewal deal?" or "Show me my meetings with Tesla in Q1."

Step 2 — The AI assistant calls the appropriate MCP tool It selects getDeal or searchMeetings with the correct parameters and sends the request to the Spotlight MCP server.

Step 3 — Spotlight returns structured data The MCP server fetches live data from Spotlight AI and returns a structured JSON response.

Step 4 — The assistant presents the result The assistant formats the data into a readable response — deal health summaries, meeting recaps, next steps, etc.

💡 Tip: When the assistant asks you to clarify (e.g. "Which Tesla deal did you mean?"), it received a multiple_results response. Just pick from the list it shows you.

Tools

getDeal

Source: DealTool.java

Retrieve enriched deal intelligence from Spotlight.ai for one or more CRM deals. Returns deal scores, MEDDIC qualification letters with colour-coded health indicators, and optionally full qualification framework data with gaps and next actions.

⚠ Requirement: At least one of dealName or dealIds must be provided. The tool returns an error immediately if neither is supplied.

Parameters

Response Statuses

Every response includes a top-level status field.

Output Schema

Deal fields (returned on success / batch_success)

MEDDIC letter object

Vector search confidence tiers

When a name search falls through to vector / semantic search, results are bucketed by confidence:

Examples

success — single deal

{  "status": "success",  "deal": {    "spotlightDealId": 4421,    "crmDealId": "SF-00892",    "dealName": "Tesla Enterprise Renewal",    "owner": "Sarah Lee",    "amount": "180000 USD",    "closeDate": "2026-06-30",    "accountName": "Tesla",    "currentStage": "Negotiation",    "forecastCategory": "Commit",    "opportunityType": "Renewal",    "spotlightScore": 68,    "meddicStatus": [      { "name": "Metrics",        "letter": "M", "color": "GREEN",  "order": 1, "completed": true,  "notes": "20% onboarding time reduction confirmed" },      { "name": "Economic Buyer", "letter": "E", "color": "YELLOW", "order": 2, "completed": false, "notes": "CFO identified but not engaged" }    ]  }}

multiple_results — name search ambiguous

{  "status": "multiple_results",  "message": "Multiple deals found. Please clarify which one you mean:",  "deals": [    { "spotlightDealId": 4421, "dealName": "Tesla Enterprise Renewal", "owner": "Sarah Lee",    "amount": "180000 USD", "closeDate": "2026-06-30", "currentStage": "Negotiation" },    { "spotlightDealId": 4398, "dealName": "Tesla Pilot — Q2",         "owner": "James Carter", "amount": "25000 USD",  "closeDate": "2026-04-30", "currentStage": "Discovery"   }  ]}

not_found

{ "status": "not_found", "query": "Acme Corp Renewal" }

searchMeetings

Source: MeetingTool.java

Search and retrieve meeting data from Spotlight.ai. Supports filtering by exact meeting ID, deal association, meeting title, participant names, and date range. Optionally return AI-generated summaries, next steps, key takeaways, risks, and full verbatim transcripts.

⚠ Requirement: At least one filter must be provided. Providing no parameters at all returns an error.

Parameters

Response Statuses

Output Schema

Response envelope (success)

MeetingView fields

Deal reference object (deal)

Examples

Metadata search — success

{  "status": "success",  "total_found": 3,  "returned": 3,  "message": "Returning 3 meetings out of 3 meetings found.",  "meetings": [    {      "meeting_id": 98231,      "title": "Tesla — Quarterly Business Review",      "date": "2026-03-28T10:00:00",      "duration_minutes": 52,      "participants": ["Mike Johnson", "Sarah Lee"],      "deal": {        "deal_name": "Tesla Enterprise Renewal",        "account_name": "Tesla",        "spotlight_deal_id": 4421,        "crm_deal_id": "SF-00892"      }    }  ]}

With summary — success

{  "meeting_id": 98231,  "title": "Tesla — Quarterly Business Review",  "recap": "The Q1 QBR with Tesla covered renewal terms, expansion scope, and integration progress.",  "summary": [    { "topic": "Renewal Terms", "details": "Both parties agreed to a 2-year renewal at current pricing." },    { "topic": "Expansion",     "details": "Expansion to 3 additional teams is under consideration pending CFO approval." }  ],  "meeting_elements": {    "next_steps":    [ "Send updated pricing proposal by April 4th", "Schedule technical deep-dive" ],    "key_takeaways": [ "Tesla is satisfied with current adoption", "Budget approval expected end of Q2" ],    "risks":         [ "Competing vendor demo scheduled for April 10th" ]  }}

not_found

{ "status": "not_found", "query": "provided filters" }

Usage Patterns

Single-call — deal by name

`User: "What's the status of the Acme Corp renewal?" Agent: [calls getDeal(dealName="Acme Corp renewal")]

success → Agent presents deal health, MEDDIC status, score multiple_results → Agent shows list, asks "Which deal did you mean?" not_found → Agent suggests: "I couldn't find that deal. Try a shorter name." `

Single-call — deal by ID

User: "Get deals 103069 and SF-00892"

Agent: [calls getDeal(dealIds=["103069", "SF-00892"])] → batch_success: presents both deals side by side

Two-call pattern — disambiguate then enrich (getDeal)

Use when the user asks for qualification details but the name is ambiguous.

Step 1 — Discover (metadata only) getDeal(dealName="Tesla") → multiple_results. Show the list. User picks "Tesla Enterprise Renewal".

Step 2 — Fetch with enrichment getDeal(dealIds=["4421"], includeFullQualificationData=true) → success with full qualification stages, gaps, and next actions.

Two-call pattern — discover then fetch (searchMeetings)

Use when the user wants a summary or transcript but hasn't provided an exact meeting ID.

Step 1 — Discover (metadata only) searchMeetings(participantNames=["Mike"], dealName="Tesla", sortBy="DATE_DESC") → Returns meeting list. Agent reads the meeting_id from the first result.

Step 2 — Fetch content by ID searchMeetings(spotlightMeetingId=98231, includeSummary=true) → Returns recap, summary topics, and next steps for exactly that meeting.

Priority Rules

getDeal priority

searchMeetings priority

⚠ Never display to users: spotlightDealId, crmDealId, spotlight_deal_id, crm_deal_id. These are internal identifiers used only for follow-up tool calls.

Troubleshooting

❌ not_found — Deal or meeting not found despite knowing it exists

The search strategy exhausted all options without a match. Common causes:

• The deal or account name is spelled differently in the CRM.

• The deal has been deleted or transferred to another team in Spotlight.

• The name is too specific — try a shorter, broader search term (e.g. just the company name).

• For meetings: check the date range — if omitted, the search is not date-restricted.

⚠ multiple_results — The assistant keeps asking me to clarify which deal

The name matched more than one deal. To resolve:

• Pick one deal from the list the assistant shows you.

• The assistant will re-call with the specific spotlightDealId (you don't need to know this number).

• Alternatively, provide a more specific name or the CRM deal ID directly next time.

⚠ confirm_account — The assistant is asking me to confirm an account name

Vector search found one possible match but isn't confident enough to proceed automatically (70–90% confidence). Simply confirm with "yes" or "no" — if no, try providing a more specific or different name.

📄 Summary or transcript is missing from the meeting response

Summaries and transcripts are opt-in and default to false. Ask specifically:

• "Show me the summary of my meeting with Tesla" → triggers includeSummary=true.

• "Show me the full transcript of meeting 98231" → triggers includeFullTranscript=true.

ℹ Note: Transcripts are very large. The assistant will only request them when you explicitly ask for the verbatim transcript and when a single meeting is expected.

❌ error — The assistant returned an error message

Errors include a referenceId field in the response. If you're reporting the issue, include this ID — it allows the team to trace the exact request in logs. Common causes:

• Missing input — no deal name or ID was provided. Try rephrasing your request with a specific deal name.

• Service unavailable — Spotlight backend is temporarily unreachable. Wait a moment and try again.

• Unexpected error — contact support with the referenceId.

🐢 The response is slow when requesting summaries

Fetching summaries or transcripts requires additional API calls to the transcription service per meeting. To minimise latency:

• Use the two-call pattern — browse metadata first, then fetch summary only for the specific meeting you want.

• Keep limit low (1–3) when summaries are requested.

• Prefer spotlightMeetingId over broad filters when you already know the meeting.