Skip to main content
The Ringee MCP server exposes 19 tools. Each is annotated with MCP trust hints so clients can decide when to ask for confirmation. Trust levels are colour-coded throughout this tab:
Read looks, never changes anything  ·  Write creates or updates a record  ·  Sensitive spends money or mints a shareable link  ·  Destructive removes access or data
No MCP tool ever debits Ringee calling credits. search_leads and reveal_lead consume the allowance of your connected enrichment provider (Apollo or Prospeo).

​
Conventions

  • Phone numbers are E.164: +14155552671.
  • Dates and times are ISO-8601 with a timezone offset: 2026-05-23T14:30:00-04:00.
  • Ids are UUIDs returned by other tools. Never invent one.
  • Paginated tools accept page (1-based, default 1) and limit (default 10, max 50).

​
Workspaces

​
list_workspaces

Lists the personal account plus every organization the user belongs to, and flags the active one. Takes no parameters.

​
switch_workspace

Changes the active workspace for every subsequent action. No re-authentication needed.
​
string
required
personal for the user’s own account, or an organization id from list_workspaces. An exact organization name also works.
See Workspaces for how scoping behaves.

​
Contacts

​
search_contacts

Searches the directory by name, phone, email, company, job title, state, website, revenue or company size. Returns id, name, phone, email and lastCallAt.
​
string
required
Search text. Pass * to list all contacts, paginated.
​
number
1-based page number.
​
number
Page size, max 50.
Use this to resolve a contactId before any tool that needs one.

​
get_contact

Fetches one contact in full, including recent calls, notes, meetings and tags.
​
string (uuid)
required
The contact to fetch.

​
find_contacts_by_outcome

Finds contacts whose calls reached given outcomes — who converted, showed interest or booked a meeting. Useful for deriving a real ICP from closed business.
​
string[]
required
One or more of meeting_booked, sale, interested, follow_up, callback_scheduled, not_interested, no_answer, voicemail, wrong_number, gatekeeper.
​
string
any (default) matches a contact with any call in those outcomes. last considers only the most recent call.
​
boolean
Include contacts flagged doNotCall or unsubscribed. Defaults to false.
​
number
1-based page number.
​
number
Page size, max 50.
Returns ICP-relevant fields — company, job title, seniority, department, country, score, lifecycle stage — plus lastOutcome and lastCallAt.

​
create_contact

​
string
required
E.164. Must be unique within the workspace — the tool fails fast on a duplicate.
​
string
Display name.
​
string
Given name.
​
string
Family name.
​
string
Primary email.
​
string
Role at the company.
​
string
Company name.
​
string
State or region.
​
string
Company website.
​
string
Company revenue or range.
​
string
Headcount band.
​
string
Lead source label. Defaults to mcp.
​
string
Initial note.
​
string[]
Tag UUIDs to assign.

​
update_contact

Patches an existing contact. Only the fields you send change.
​
string (uuid)
required
The contact to update.
​
string[]
Replaces the contact’s tag set. Omit it to leave tags untouched.
All other fields match create_contact. Ownership is verified before writing.

​
delete_contact

Destructive Soft-deletes a contact by setting deletedAt.
​
string (uuid)
required
The contact to delete.
​
boolean
required
Must be the literal true.
​
string
required
Must exactly match the contact’s stored phone number in E.164.
Destructive and double-guarded. Fetch the contact with get_contact first, read the phone number back to the user, and get an explicit “yes, delete” before calling. Assistants must never auto-confirm.

​
Calls and follow-ups

​
list_calls

Returns calls in full detail: direction, status, timing, duration, logged outcome and note, plus the transcription and recording URL when present. Newest first. Cost and low-level telephony fields are intentionally excluded.
​
string (uuid)
Filter to one contact’s calls.
​
string[]
Only calls with one of these outcomes.
​
string[]
Only calls in these states: pending, ringing, answered, recording, completed, failed.
​
string (ISO-8601)
Only calls created at or after this.
​
string (ISO-8601)
Only calls created at or before this.
​
number
1-based page number.
​
number
Page size, max 50.

​
log_call_outcome

Records how a past call went.
​
string (uuid)
required
An existing call belonging to the active workspace.
​
string
required
One of the CallOutcome values listed under find_contacts_by_outcome.
​
string
Free-text note.

​
create_callback

Schedules a reminder to call a contact back. Creates a callback task and a reminder.
​
string (uuid)
required
Who to call back.
​
string (ISO-8601)
required
Future datetime with offset.
​
string (uuid)
Originating call.
​
string
Free-text note.

​
schedule_meeting

Books a meeting. When the user has a Google or Microsoft calendar connected, the event is synced and a Meet or Teams link is generated.
​
string (uuid)
required
Who the meeting is with.
​
string (ISO-8601)
required
Start time with offset.
​
string
Meeting title.
​
number
Minutes. Defaults to 30.
​
string
Address or video URL.
​
string
Notes.
​
string
Sends a calendar invite to this address.
​
string
Calendar to sync with.
​
string (uuid)
Originating call.
This tool reaches an external system (calendar sync and email invites), so it is flagged openWorldHint.

​
Call sessions

A call session is a queue of contacts plus a magic link that lets someone dial through them one by one — without logging in.

​
create_call_session

Sensitive
​
object[]
required
Ordered queue, 1 to 500 entries. Each accepts contactId and/or phoneNumber (E.164, required when contactId is absent), plus optional name, company, jobTitle, state, website, revenue, companySize. Provide contactId when you have it — name and phone are then looked up server-side.
​
string
Session title, visible to the magic-link recipient.
​
string (uuid)
Attribute calls to a campaign.
​
number
Link lifetime. Defaults to 60 minutes, max 30 days.
​
number
Auto-complete the session after N calls, max 500.
​
object
Free-form JSON persisted with the session; not exposed to the magic-link UI.
Returns a joinUrl containing a magic-link token. The token is shown once and cannot be re-fetched. Share the URL exactly as returned, and only with someone authorized to call on the workspace’s behalf.

​
get_call_session

Returns safe metadata — status, contact count, calls completed, expiry, and whether a token is still active. It never exposes the raw magic link.
​
string (uuid)
required
The session to inspect.

​
update_call_session

​
string (uuid)
required
The session to update.
​
string
New title.
​
string (uuid) | null
Set a campaign, or null to detach.
​
number
Extend validity.
​
object[]
Replaces the queue. Only allowed before the first call has started.
​
object
Replace metadata.

​
delete_call_session

Destructive Revokes the session. Past calls are preserved, but every active magic link stops working immediately.
​
string (uuid)
required
The session to revoke.
Flagged destructive — the link cannot be restored. Issue a new session instead.

​
Lead prospecting

These tools use the workspace’s connected enrichment provider. Apollo is preferred when both are connected.

​
search_leads

Searches for candidates. Results are not contacts yet.
​
string
apollo or prospeo. Auto-selected when omitted.
​
string
Free-text keywords.
​
string[]
Job titles to include.
​
string[]
Job titles to exclude.
​
string[]
Seniority levels.
​
string[]
Departments.
​
string[]
Countries.
​
string[]
Cities.
​
string[]
Industries.
​
string[]
Company names.
​
string[]
Company domains.
​
string[]
Headcount bands.
​
string[]
Technologies in use.
​
boolean
Only candidates with an email.
​
boolean
Only candidates with a phone.
​
boolean
Only verified emails.
​
number
Page number.
​
number
Results per page, max 25.
Returns a jobId plus candidates with externalId, person and company summaries, and whether emails and phones are available. Pass the jobId to the two tools below.

​
reveal_lead

Sensitive Spends provider credits Reveals a candidate’s email — and optionally a mobile phone — and upserts a Ringee contact so the lead is immediately callable.
​
string (uuid)
required
From search_leads.
​
string
required
The candidate to reveal.
​
boolean
Also reveal a mobile phone. Costs extra provider credits.
Spends the enrichment provider’s credits every time and is not idempotent. Call it only after the user explicitly picks that lead.

​
import_leads_as_contacts

Bulk-imports candidates from a search job as Ringee contacts, deduplicated by phone number. Does not reveal hidden emails or phones — use reveal_lead first if you need those.
​
string (uuid)
required
From search_leads.
​
string[]
required
Candidates to import.
​
string[]
Tags to assign to every imported contact.
Returns counts, duplicates, errors and the new contact ids.

​
Placing calls

There is no tool that dials a number. Calls are placed in the user’s browser or mobile app over WebRTC, so an assistant cannot start one server-side. To get someone dialing from a chat, use create_call_session and share the joinUrl.

​
Next steps

Workspaces

How personal and organization scoping works

Safety

Confirmation rules for sensitive actions