---
title: SkipCalls for developers and AI agents
description: Connect to the SkipCalls MCP server or REST API to run an AI phone receptionist.
source: https://skipcalls.com/developers.md
---

# SkipCalls for developers and AI agents

SkipCalls is an AI phone receptionist: it answers a business's calls 24/7, captures leads, books appointments and texts callers back. Any MCP client (Claude, ChatGPT, Cursor, Codex, your own agent) can set it up and run it for the signed-in owner.

## Connect

- MCP endpoint: `https://be.skipcalls.com/mcp` (Streamable HTTP, JSON-RPC 2.0, responses as JSON or SSE, `Mcp-Session-Id` session header). SSE fallback: `https://be.skipcalls.com/sse`.
- Auth: OAuth 2.1 Authorization Code with PKCE S256, dynamic client registration, no client secret. Step-by-step runbook: https://skipcalls.com/auth.md
- An unauthenticated request gets HTTP 401 with `WWW-Authenticate: Bearer resource_metadata="https://be.skipcalls.com/.well-known/oauth-protected-resource"`.
- Server-to-server: a SkipCalls API key as `Authorization: Bearer <key>` (PRO plans and above).

## Machine-readable discovery

| Resource | URL |
| --- | --- |
| MCP descriptor with all tool schemas | https://skipcalls.com/.well-known/mcp.json |
| MCP server card | https://skipcalls.com/.well-known/mcp/server-card.json |
| OpenAPI 3.1 for the MCP transport (`x-mcp-tools`) | https://skipcalls.com/openapi.json |
| REST API OpenAPI | https://be.skipcalls.com/api-public-json |
| API catalog (RFC 9727) | https://skipcalls.com/.well-known/api-catalog |
| Agent resource descriptor | https://skipcalls.com/.well-known/ard.json |
| Agent skills index (sha256 digests) | https://skipcalls.com/.well-known/agent-skills/index.json |
| OAuth protected resource (RFC 9728) | https://be.skipcalls.com/.well-known/oauth-protected-resource |
| OAuth authorization server (RFC 8414) | https://be.skipcalls.com/.well-known/oauth-authorization-server |
| Short context | https://skipcalls.com/llms.txt |
| Full context | https://skipcalls.com/llms-full.txt |
| Security contact | https://skipcalls.com/.well-known/security.txt |

## Working rules for agents

1. Call `getOverview` first (how SkipCalls works and which tool does what), then `listAgents` or `statusReport` for the account. Never guess IDs: read them from a list tool.
2. Never invent contact details, prices or business facts. Ask the user.
3. Before any write tool, show the exact change and get the user's yes in the conversation.
4. "Accepted" is not "delivered": a sent SMS or scheduled call is queued; read it back (`getTextConversation`, `getCallDetails`) before telling the user it happened.
5. Recordings are not streamed into the chat: `getCallDetails` returns a share link to the call page (recording, summary, transcript); give the user that link.

## Tools (100)

### Read tools (48)

| Tool | What it does |
| --- | --- |
| `agent_functions_get_code` | Read one Code function's full editable definition by its ID from agent_functions_list: name, description, instruction, active state, language, source, input schema and saved tests. |
| `agent_functions_get_guide` | Return the exact Code function contract: main(input, context), runtime context fields, sandbox limits, saved test-case shape and examples. |
| `agent_functions_list` | List the account's Agent Functions (HTTP webhooks, connected MCP tools and Code functions) with safe summaries. |
| `agent_functions_run_tests` | Run one Code function's saved tests in the sandbox and return each result. |
| `agent_tasks_list` | List a receptionist's call tasks (what it collects or accomplishes on every call), the standard tasks that can be enabled, and the remaining custom-task budget. |
| `app_getCall` | Get one call by its UUID with everything the Calls inbox shows: caller or recipient, status, start time, minutes, the AI summary, the call goal (outbound), the spoken transcript as speaker turns, and a dashboard link (webUrl). |
| `app_listCalls` | List one page of calls (inbound and outbound merged), newest first: id, direction, title, caller or recipient name and phone, status, start time, minutes and a summary preview. |
| `business_qa_list` | List every Business Profile question with its current answer and ID: the short facts the receptionist uses on every call (hours, services, pricing, location, policies). |
| `business_qa_list_profiles` | List the businesses (Business Profiles) on this account and the receptionists attached to each. |
| `calendar_list` | List every calendar connected to the receptionists with its booking settings (work hours, appointment length, buffer, timezone, double-booking, cancellation) and 4-character calendar IDs. |
| `calendar_list_events` | List the events already booked on one date (YYYY-MM-DD in the owner's timezone, default today) across every connected calendar, so you can answer "what's on my calendar". |
| `estimates_get` | Read the owner's Estimates prices in plain words, any open assumption, and whether Estimates and quoting on calls are on. |
| `estimates_try` | Show the estimate a caller who says the given words would get from the current prices. |
| `findAppointments` | Find appointments tracked by SkipCalls using a guest name, phone, email, title, period, or exact ISO date range. |
| `findCalendarSlots` | Find real bookable appointment slots in the user's active connected calendars. |
| `get_contact` | Get one contact by ID: name, phone, email, company, tags, notes, lifecycle stage, Skip AI (bypassReceptionist), do-not-call/SMS flags, custom fields, and the 5 newest timeline events. |
| `get_contact_timeline` | Get one contact's full interaction history in one list, newest first: inbound and outbound calls, SMS, jobs, follow-ups, appointments, notes, document uploads and field changes. |
| `get_work` | Read one Needs you item: customer, what to do, the prepared text and recipient, caller quotes, calls, texts already sent, due. |
| `getAccount` | Identify the connected SkipCalls account: business name, workspace ID, timezone, the person on this connection vs the workspace owner, team size, receptionists (ID, name, active), phone numbers, and the current plan and minute balance (in ChatGPT, billing is replaced by the SkipCalls dashboard link). |
| `getAgent` | Get rich detailed receptionist info: config, instructions, connected resources, management pointers, knowledge, and stats. |
| `getAvailableVoices` | List voices the user can select for a receptionist as a compact table: display name, exact id, style tags, which receptionist currently uses it, and a preview link. |
| `getBillingInfo` | In ChatGPT, billing is unavailable: return the SkipCalls dashboard link, without plans, prices, or checkout. |
| `getCallDetails` | Get everything about one call by its UUID, inbound or outbound (detected automatically): who called or was called, status, time, receptionist, AI summary, transcript, and a signed public share link to the call page (recording, summary, transcript) the user can open or share. |
| `getCallHistory` | Compact list of the user's calls. |
| `getCarrierForwardingInfo` | Get verified carrier-specific call-forwarding codes or portal steps with the user's SkipCalls number filled in. |
| `getOverview` | REQUIRED READING for any external assistant connecting over MCP. |
| `getTextConversation` | Read the messages of one SMS, email or website-chat thread, up to 10 per page, without marking it read or changing anything. |
| `knowledge_get_page` | Read the complete text and last-updated timestamp of one Knowledge Base text page, by the ID from knowledge_list_pages. |
| `knowledge_list_pages` | List every Knowledge Base text page (the longer reference documents the receptionist can look up on calls) with its ID and title, no body text. |
| `lead_alerts_get` | Read one receptionist's Lead Alerts: whether they are on and the ordered rules that call or text a team member after a matching inbound call, with rule IDs. |
| `list_customer_files` | List the files a customer uploaded through an upload link from create_upload_link (photos, PDFs, documents), newest first. |
| `list_work` | List Needs you items, the to-do list SkipCalls keeps for the owner: follow-ups from calls and reminders, each with its id, customer, what to do and due time. |
| `listAgents` | Get list of all voice agents for the user. |
| `listCallScenarios` | List one receptionist's Skills / Call Scenarios, including IDs, stable keys, selectors, full guides, enabled state, and order. |
| `listTextConversations` | List the newest text conversations (SMS, email, website chat), one preview per thread with its conversationId, newest first. |
| `loadSkill` | Load one SkipCalls expert workflow before writing or multi-step work: receptionist-setup before drafting call instructions or greetings, full-duplex-prompting for GPT-Live receptionists, call-scenario-management for Call Scenarios, call-improvement for one specific call, call-insights for what callers want and missed demand, forwarding for carrier forwarding, plus onboarding, calendar, contacts, lead alerts, text conversations, code functions, and app navigation. |
| `memory_list` | List what SkipCalls remembers about the person on this connection and the workspace (name, reply and report preferences, standing rules, links, date-bound facts), each with its ID. |
| `notification_settings_get` | Read the owner's notification settings: email and call-summary notifications, new-message, spam and abandoned-call alerts, important-call SMS, Daily Recap and Weekly Report, Needs-you reminders, recipients and delivery times. |
| `onboarding_get_status` | Read where first-time SkipCalls setup stands and the one next step: Business Profile category and address, subscription, first receptionist with its automatically assigned phone number, and optional calendar connection. |
| `onboarding_list_business_categories` | List the canonical business categories with their IDs. |
| `onboarding_start_calendar_connection` | Return the secure link that connects Google Calendar or Outlook. |
| `openCallsInbox` | Open the interactive SkipCalls Calls inbox: recent inbound and outbound calls with summaries and transcripts. |
| `previewReceptionistGreeting` | Speak a receptionist's greeting in the receptionist's own voice and return a link to an MP3 the owner can open and play. |
| `search` | Targeted search across calls, contacts, SMS, or knowledge. |
| `search_mentions` | Typeahead for the ChatGPT composer @-mention menu: up to 8 matching SkipCalls contacts and recent calls as resource links the user can attach. |
| `searchHelpCenter` | Search the official SkipCalls product documentation (help center) with vector search. |
| `statusReport` | Get a receptionist/workspace health report for questions like "How is my receptionist doing?", "How are things?", or "What needs attention?". |
| `transfer_numbers_list` | List a receptionist's transfer numbers (where it hands off live calls) in priority order, with their 4-character IDs, schedules, warm/cold mode and active state. |

### Write tools (52)

⚠️ marks tools with real side effects that cannot be previewed: they send a text, place a call, delete or overwrite data. Show the user the exact change and get a yes right before calling them.

| Tool | What it does |
| --- | --- |
| `addToContacts` ⚠️ | Create or update a contact by phone number. |
| `agent_functions_attach` | Attach an existing Agent Function to one receptionist so it can call it on live calls. |
| `agent_functions_create_code` | Create a sandboxed Code function with saved tests, for logic the receptionist runs on live calls (calculations, lookups in fixed data). |
| `agent_functions_create_http` | Create an HTTP/webhook Agent Function the receptionist calls during live calls. |
| `agent_functions_update_code` ⚠️ | Replace one Code function (functionId from agent_functions_list) with a complete new definition: every field is required, so start from agent_functions_get_code and change only what the user asked. |
| `agent_tasks_add` | Enable one call task on a receptionist. |
| `agent_tasks_delete` ⚠️ | Remove one call task from a receptionist by taskId. |
| `bookCalendarSlot` | Create one appointment in the user's connected calendar at an exact slot returned by findCalendarSlots. |
| `business_qa_create` | Add one custom question and answer to the Business Profile. |
| `business_qa_delete` ⚠️ | Delete one Business Profile question and its answer by questionId. |
| `business_qa_update` ⚠️ | Replace the answer to one Business Profile question by questionId. |
| `calendar_update_settings` ⚠️ | Change the booking settings of one connected calendar by calendarShortId; send only the fields that change. |
| `call_scenarios_create` | Create one Call Scenario (Skill) on a receptionist: when it applies and the step-by-step guide the receptionist follows. |
| `call_scenarios_delete` ⚠️ | Delete one Call Scenario by scenarioId. |
| `call_scenarios_reorder` ⚠️ | Set the order of a receptionist's Call Scenarios. |
| `call_scenarios_update` ⚠️ | Change the title, when-to-use selector, guide text or enabled state of one Call Scenario by scenarioId. |
| `cancel_reminder` ⚠️ | Cancel one pending reminder the user no longer wants, by the id from create_reminder or list_work (view snoozed). |
| `cancelAppointment` ⚠️ | Cancel one exact SkipCalls-tracked appointment at the calendar provider. |
| `cancelCall` ⚠️ | Cancel a scheduled outbound call that has not been placed yet. |
| `create_contact_note` | Add a new note to a contact's record, e.g. |
| `create_reminder` | Create a reminder when the user says "remind me …": it waits under Later in Needs you and, at the given time, notifies them with a SkipCalls chat ready to continue. |
| `create_upload_link` | Generate a public upload link for a contact so they can attach files (photos, PDFs, docs). |
| `estimates_confirm_assumption` | Accept the open assumption shown by estimates_get as correct, so it is closed. |
| `estimates_set_enabled` | Turn Estimates on or off. |
| `estimates_set_quote_on_calls` | Allow or stop the receptionist saying estimate prices to callers on calls. |
| `estimates_start_over` ⚠️ | Delete the Estimates prices and their Undo copy. |
| `estimates_undo` ⚠️ | Put back the Estimates prices from before the last estimates_update_prices change, when the owner says the change was wrong ("undo that"). |
| `estimates_update_prices` ⚠️ | Change or add Estimates prices from the owner's exact words, passed verbatim. |
| `knowledge_create_page` | Create one Knowledge Base text page the receptionist can cite on calls. |
| `knowledge_update_page` ⚠️ | Replace the title and/or complete text of one Knowledge Base text page. |
| `lead_alerts_replace` ⚠️ | Replace one receptionist's complete Lead Alert setup: the enabled state and the full ordered rule list. |
| `memory_forget` ⚠️ | Stop using one remembered fact by memoryId when the person asks SkipCalls to forget it. |
| `memory_remember` | Save one durable fact when the person asks SkipCalls to remember it for future conversations; pass replacesMemoryId to correct an existing one. |
| `notification_settings_update` ⚠️ | Change one or more notification settings; send only the settings the user asked to change. |
| `onboarding_complete_receptionist_setup` | Finish an existing receptionist that has no phone number yet by assigning one automatically, without changing its settings. |
| `onboarding_create_receptionist` | Create the first receptionist and assign it a phone number automatically (the user never picks or buys the first number separately). |
| `onboarding_save_business_profile` ⚠️ | Save the business name, category and address on the Business Profile during setup. |
| `reportCallIssue` | Record one privacy-safe issue as negative feedback on a specific call after getCallDetails provides concrete evidence. |
| `runForwardingTestCall` ⚠️ | Place an automated call to the user's regular phone number and verify that carrier forwarding reaches the active SkipCalls receptionist. |
| `scheduleCall` ⚠️ | Place or schedule an OUTBOUND phone call on behalf of the user. |
| `sendCallFollowUp` ⚠️ | Send one EMAIL or SMS follow-up tied to an exact completed inbound call that is linked to a contact. |
| `sendSms` ⚠️ | Send an SMS from the user to a phone number that is eligible for messaging. |
| `startSubscriptionCheckout` | In ChatGPT, checkout is unavailable: return the SkipCalls dashboard link and do not create a session. |
| `transfer_numbers_add` | Add one transfer number to a receptionist (max 20). |
| `transfer_numbers_delete` ⚠️ | Permanently remove one transfer number by transferShortId. |
| `transfer_numbers_reorder` ⚠️ | Set the priority order of all of a receptionist's transfer numbers (the order the receptionist tries them when transferring a caller). |
| `transfer_numbers_update` ⚠️ | Change one transfer number by transferShortId: label, description, phone number, schedule (clearWorkHours=true makes it 24/7), warm/cold mode, or isActive=false to pause it while keeping its setup. |
| `update_contact` ⚠️ | Update fields on a contact. |
| `update_work` ⚠️ | Mark one Needs you item done or not_needed (optional short note), snooze it (later), or set/clear its due time, when the user asks. |
| `updateAgent` ⚠️ | Update one SkipCalls receptionist's configuration. |
| `updateOutbound` ⚠️ | Update the goal of one queued outbound call in place. |
| `updateTimezone` ⚠️ | Update the user profile timezone (IANA format, e.g. |

Full input schemas: https://skipcalls.com/.well-known/mcp.json (also `x-mcp-tools` in https://skipcalls.com/openapi.json).

## REST API

Base URL `https://be.skipcalls.com`, OpenAPI at https://be.skipcalls.com/api-public-json, playground at https://app.skipcalls.com/api-playground.

## Support

team@skipcalls.com · https://skipcalls.com