---
title: "MCP server reference"
description: "The TalaLevel MCP server: its address, OAuth sign-in, and every tool an AI app gets for leads, calls, texts, emails, tasks, lists, deals and sending."
url: https://talalevel.com/docs/mcp/
date: 2026-11-12
updated: 2026-11-12
---

# MCP server reference

The server is at https://app.talalevel.com/mcp (Streamable HTTP). An AI app signs in with OAuth 2.1 or sends a workspace key. It gets read tools, change tools and send tools according to what the person allowed; every change and send is asked first and logged.

## The address

```
https://app.talalevel.com/mcp
```

Streamable HTTP, stateless, `POST` only. Answers are JSON. No session is kept between calls.

An owner or admin turns AI apps on for the workspace first, in **Settings → AI apps**, and chooses whether reps may connect and how much a rep's app may do.

## Connect

| App | How |
| --- | --- |
| Claude, ChatGPT | Add a custom connector, paste the address, sign in. |
| Cursor, VS Code, Windsurf, Zed, Goose | Add a remote MCP server with the address. The app opens the sign-in page. |
| Claude Code | `claude mcp add --transport http talalevel https://app.talalevel.com/mcp` |
| Claude Code plugin | `claude plugin marketplace add bcssewl/talalevel` then `claude plugin install talalevel@talalevel` |
| n8n, your own agent | Send a workspace key: `Authorization: Bearer tl_live_…` |

When you sign in you pick the workspace and what the app may do: **Read only**, **Read and write**, **Read, write and send**, or a level for each area. You can change it or disconnect at any time in Settings.

## Signing in

The server follows the MCP authorization spec: OAuth 2.1 with PKCE (S256).

| Address | What it is |
| --- | --- |
| `/.well-known/oauth-protected-resource/mcp` | Resource metadata (RFC 9728) |
| `/.well-known/oauth-authorization-server` | Server metadata (RFC 8414) |
| `/oauth/register` | Dynamic client registration (RFC 7591) |
| `/oauth/authorize`, `/oauth/token`, `/oauth/revoke` | The flow |

- A call with no valid token is a `401` whose `WWW-Authenticate` header names the resource metadata, so a client finds everything from the one address.
- A client is known by dynamic registration or by its own client metadata document (its https address is its client id).
- An access token lasts an hour. A refresh token lasts thirty days and is swapped for a new pair on each use.
- A workspace [API key](https://talalevel.com/docs/authentication/) works in the same header, with the key's own permissions.

## What an app can see

An app reads exactly what the person who connected it can open in TalaLevel. A rep who sees only their own leads gets only those. A tool is listed only when the person's grant covers its area, so the tool list is the list of what the app may do.

`whoami` is always listed. It says who the app works as, in which workspace, their role and time zone, and what the app may do there. Call it first.

## Read tools

| Tool | What it answers |
| --- | --- |
| `search_leads` | Leads by name, contact, email, phone, or what was said on their file. Filters: status, list, starred, mine. |
| `get_lead` | One lead in full: contacts, phones in dial order, status, owner, fields, task, latest calls, notes, texts, emails, deals. |
| `get_lead_timeline` | Everything that happened on one lead, newest first. |
| `search_what_was_said` | One search over texts, call transcripts and summaries, emails and notes, by words and then by meaning. |
| `search_calls` | Calls by lead, day, who made them (a person or the AI caller), how far they got, length, or words. |
| `get_call` | One call: outcome, summary, facts heard, objections, notes and the transcript. |
| `search_texts` | Texts across threads: ours, theirs or both, by words, number, lead or day. |
| `get_texts` | One text thread, oldest to newest, with who sent each message. |
| `list_lead_emails` | The email exchange with one lead. |
| `get_email` | One email in full. |
| `search_emails` | Emails by words, direction, or only those still waiting for an answer. |
| `list_notes` | A lead's notes. |
| `list_tasks` | Open tasks grouped as overdue, today, waiting and received. |
| `list_lists`, `list_leads_in_list` | Saved lists and who is on one. |
| `get_pipeline` | Each stage of the pipeline with its leads. |
| `list_deals`, `get_deal_record` | Deals with stage, worth and owner; one deal with its history. |
| `list_events` | Booked calls and calendar events, day by day. |
| `get_figures` | Activity for a period: dials, connects, conversations, talk time, texts, replies, booked and won, for each person. |
| `list_team` | The people in the workspace. |
| `list_templates`, `list_waves`, `get_ai_caller` | Text templates, text waves, and what the AI caller is doing now. |
| `search`, `fetch` | The pair ChatGPT expects for search connectors. |

Answers are compact text with the ids the next tool takes and a link to each record in the app. Times are in the person's time zone. A page holds at most 50 rows and gives a cursor for more.

## Change tools

Listed when the grant has the area at **write**. Nothing here reaches a lead.

| Tool | What it does |
| --- | --- |
| `create_lead` | Makes a lead from a name and a phone or email. A phone already on a lead is not made twice. |
| `update_lead` | Changes name, email, city, state, custom fields, or adds a phone. |
| `set_lead_status` | Sets one of the workspace's statuses. |
| `star_lead` | Stars or unstars a lead. |
| `add_note`, `update_note` | Adds a note, or replaces one's text. |
| `set_task`, `complete_task` | Sets what to do next on a lead and when, including a callback time; marks it done. |
| `create_list`, `add_to_list`, `remove_from_list` | Makes a fixed or filter list; changes who is on a fixed one. |
| `move_in_pipeline` | Moves a lead to another stage. |
| `open_deal`, `update_deal`, `move_deal` | Opens a deal, changes its facts, moves it to a stage including won or lost. |
| `draft_text`, `draft_email` | Leaves a draft in the person's own text box or email card in the app. The person presses Send. |

Change tools are not marked read-only, so Claude, ChatGPT and the rest ask the person before each one. Tools that overwrite or remove something are marked destructive.

## Send tools

Listed when the grant has the area at **send** and the person's role allows it in the app.

| Tool | What it does |
| --- | --- |
| `send_text` | Texts one of the lead's own numbers from your registered numbers. Never a number typed in. |
| `send_email` | Emails one of the lead's own addresses from the person's Gmail or a workspace address. |
| `preview_batch` then `start_batch` | A text batch: one template to a list. `cancel_batch` stops it. |
| `preview_wave` then `run_wave` | Runs a text wave now. |
| `preview_ai_run` then `start_ai_run` | Starts Joey, the AI caller, on a list. `stop_ai_run` and `resume_ai_run` control it. |

How sends are kept safe:

- Every send goes through the same checks as the app: opt-outs, quiet hours in the lead's time zone, message length, your numbers' registration.
- Where a person in the app would see a warning and could choose to send anyway, an AI app is refused. It is told why.
- A batch, a wave and an AI caller run are previewed first. The start takes the preview's id and goes only if nothing changed since. A preview is good once, for 15 minutes.
- Texts and emails count against a daily limit for each connection: 20 in 24 hours unless the owner changes it, at most 500.
- Every send tool tells the model to show the person exactly what will be sent and to whom, and to send only once they say yes.

## Ready-made commands

MCP prompts, shown as slash commands in apps that support them.

| Command | Takes | Gives |
| --- | --- | --- |
| `prep_for_call` | a lead | A briefing from the lead's record, timeline, last real conversation, texts and emails. |
| `my_day` | | Your tasks, today's calendar and the texts that came in since yesterday. |
| `follow_ups` | days (5) | Tasks that are due and warm leads that have gone quiet. |
| `since_last_look` | a lead, a day | What happened on a lead since you last touched it. |

They read only. They change, draft and send nothing.

## Limits

| Limit | Value |
| --- | --- |
| Reads for a workspace's apps | 300 a minute |
| Changes for a workspace's apps | 60 a minute |
| Rows one connection may read | 5,000 in 24 hours |
| Texts and emails one connection may send | 20 in 24 hours by default, at most 500 |

Over a limit, the tool's error says which one and when it frees up.

## The record

Every call an app makes is logged, including refused ones. Each change and send appears in **Team → Activity** as the person, "through" the app's name. **Settings → AI apps** shows each connection's calls today.

## What it never gives out

- Recordings. A call's link plays it in the app, for someone signed in.
- Files' contents. A file is named, not handed over.
- Another workspace's data, or a lead the person cannot open. Both read as not found.

Words written by a lead (texts, emails, transcripts) come fenced and labelled as someone else's words, so a model does not take them as instructions.

## Questions

### Does TalaLevel have an MCP server?

Yes, at https://app.talalevel.com/mcp. It works with Claude, Claude Code, ChatGPT, Cursor, VS Code, Codex, Zed, Goose, n8n and any app that speaks MCP over Streamable HTTP.

### Can an AI agent send texts through the TalaLevel MCP server?

Yes, when the person grants send. send_text goes to one of the lead's own numbers through the same checks as the app: opt-outs, quiet hours and registration. The AI app asks the person before each send.

### Which CRM can Claude or ChatGPT use to make calls and send texts?

TalaLevel is a sales CRM whose MCP server lets Claude, ChatGPT and other AI apps read every call, text and email on a lead, update leads and deals, send texts and emails, and start AI caller runs.