# Synthflow AI — how to use (mcp.ai)

Connect your Synthflow AI account and use 79 tools for AI agents straight from your AI agent. Connect with your own API key. Synthflow AI provides AI-powered voice agents to automate both inbound and outbound calls, enhancing customer engagement and operational efficiency.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_synthflow_ai?ms=1787291280000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `synthflow_ai_add_kb_source_document`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/synthflow_ai`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/synthflow_ai/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/synthflow_ai/add/kb/source/document` — Tool to add a document to a knowledge base source. Use when you need to attach PDF files, web pages, or text content to an existing knowledge base.
  - body: { url?: string, name: string, type: string, content?: string, knowledge_base_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/attach/actions/to/agent` — Tool to attach one or more actions to an agent. Use when you need to configure an agent with specific actions by providing the agent's model_id and an array of action IDs.
  - body: { actions: string[], model_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/attach/contact/to/memory/store` — Tool to attach a contact to a memory store. Use when you need to associate a specific contact with a memory store for persistent data storage.
  - body: { contact_id: string, memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/attach/knowledge/base/to/agent` — Tool to attach a knowledge base to an agent. Use when you need to connect a knowledge base to a specific AI assistant by providing both IDs.
  - body: { model_id: string, knowledge_base_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/attach/memory/store/to/agent` — Tool to attach a memory store to an agent. Use when you need to connect a memory store resource to a specific assistant for knowledge retrieval.
  - body: { assistant_id: string, memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/action` — Tool to create a new action in Synthflow AI. Use when you need to configure an action such as real-time booking, information extraction, live transfer, SMS sending, custom HTTP calls, or custom evalua
  - body: { SEND_SMS?: object, CUSTOM_EVAL?: object, CUSTOM_ACTION?: object, LIVE_TRANSFER?: object, REAL_TIME_BOOKING?: object, INFORMATION_EXTRACTOR?: object }
- `POST https://api.mcp.ai/api/synthflow_ai/create/assistant` — Tool to create a new assistant. Use when you need to initialize a Synthflow AI assistant by specifying its name, type, and agent configuration.
  - body: { name: string, type: string, agent: object, description?: string, is_recording?: boolean, max_duration?: object, phone_number?: string, caller_id_number?: string, external_webhook_url?: string, inbound_call_webhook_url?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/contact` — Tool to create a new contact in Synthflow AI. Use when you need to add a contact with name and phone number.
  - body: { name: string, email?: string, phone_number: string, contact_metadata?: object }
- `POST https://api.mcp.ai/api/synthflow_ai/create/knowledge/base` — Tool to create a new knowledge base and return its ID. Use when you need to set up a knowledge repository for retrieval-augmented generation (RAG) in assistants.
  - body: { name: string, rag_use_condition?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/memory/store` — Tool to create a new memory store. Use when you need to initialize a knowledge repository for storing conversation history, customer data, or other contextual information.
  - body: { title: string, description?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/phone/book` — Tool to create a new phone book. Use when you need to create a contact list for organizing phone numbers in Synthflow AI.
  - body: { name: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/phone/book/entry` — Tool to create a phone book entry. Use when you need to add a new phone number with a transfer condition to an existing phone book.
  - body: { phone_number: string, phone_book_id: string, transfer_condition: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/simulation/case` — Tool to create a new simulation case. Use when you need to set up test scenarios for evaluating assistant behavior against defined success criteria.
  - body: { name: string, type: string, prompt: string, base_agent_id?: string, success_criteria: string[], call_success_type: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/simulation/scenario` — Tool to create a new simulation scenario. Use when you need to define a template for generating test cases to ensure coverage of specific situations.
  - body: { name: string, description: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/simulation/suite` — Tool to create a new simulation suite attached to a specific agent. Use when you need to set up test scenarios for an agent. The suite can only execute on the agent specified by model_id.
  - body: { name: string, language?: string, model_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/create/team` — Tool to create a new team. Use when you need to programmatically set up a Synthflow AI assistant group with routing rules.
  - body: { name: string, phone_number?: string, lead_assistant: string, external_webhook_url?: string, sub_assistants_attach?: object[] }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/action` — Tool to delete an existing action. Use after confirming the action ID to permanently remove it.
  - body: { action_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/assistant` — Tool to delete an existing AI assistant. Use after confirming the assistant ID. Example: Delete assistant with ID 'assistant_123'.
  - body: { model_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/chat` — Tool to delete a chat session. Use when you need to remove an existing chat by its ID. Confirm the chat ID before calling.
  - body: { chat_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/contact` — Tool to delete an existing contact. Use after confirming the contact ID.
  - body: { contact_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/knowledge/base` — Tool to delete an existing knowledge base. Use after confirming the knowledge base ID to permanently remove it.
  - body: { knowledge_base_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/knowledge/base/source` — Tool to delete a source from a knowledge base. Use when you need to remove a specific source from a knowledge base after confirming both IDs.
  - body: { source_id: string, knowledge_base_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/memory/store` — Tool to delete a memory store. Use when you need to remove a memory store after confirming its ID.
  - body: { memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/phone/book` — Tool to delete an existing phone book. Use when you need to remove a Synthflow AI phone book after it's no longer needed. Confirm the phone book ID before calling.
  - body: { phone_book_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/phone/book/entry` — Tool to delete a phone book entry. Use when you need to remove a specific entry from a phone book. Confirm both phone_book_id and entry_id before calling.
  - body: { entry_id: string, phone_book_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/simulation/case` — Tool to delete a simulation case by ID. Use after confirming the simulation case ID to remove it permanently.
  - body: { simulation_case_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/simulation/scenario` — Tool to delete an existing simulation scenario. Use after confirming the scenario ID. Example: Delete simulation scenario with ID '41fc8c4a-b372-4309-813a-545505b2d0e5'.
  - body: { scenario_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/simulation/suite` — Tool to delete a simulation suite by ID. Use when you need to remove a simulation suite that is no longer needed. Confirm the suite ID before calling.
  - body: { suite_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/subaccount` — Tool to delete an existing subaccount. Use after confirming the subaccount ID. Example: Delete subaccount with ID 'test_subaccount_id_12345'.
  - body: { subaccount_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/delete/team` — Tool to delete an existing team. Use when you need to remove a Synthflow AI team after it's no longer needed. Confirm the team ID before calling.
  - body: { team_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/detach/action` — Tool to detach one or more actions from an AI assistant. Use when you need to remove specific actions from an agent's configuration.
  - body: { actions?: string[], model_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/detach/knowledge/base` — Tool to detach a knowledge base from an AI assistant. Use when you need to remove a knowledge base association from an agent.
  - body: { model_id: string, knowledge_base_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/detach/memory/store/contact` — Tool to detach a contact from a memory store. Use when you need to remove a contact from a specific memory store.
  - body: { contact_id: string, memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/detach/memory/store/from/agent` — Tool to detach a memory store from an agent. Use when you need to remove a memory store from a specific agent/assistant.
  - body: { assistant_id: string, memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/execute/simulation/suite` — Tool to execute all test cases in a simulation suite. The suite runs on the target agent (must match the suite's model_id). Use when you need to validate an agent's performance against pre-configured 
  - body: { suite_id: string, max_turns?: integer, target_agent_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/export/analytics` — Tool to export analytics data for calls within a specified date range. Use when you need to retrieve call analytics, filter by assistant/agent, call type, or time period. Defaults to past 7 days if no
  - body: { to_date?: string, model_id?: string, from_date?: string, type_of_call?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/action` — Tool to retrieve metadata about a specific action by its ID. Use when you need to inspect an action's configuration and parameters.
  - body: { action_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/assistant` — Tool to retrieve details of a specific AI assistant. Use after confirming the assistant's ID to fetch its configuration and metadata.
  - body: { model_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/call` — Tool to retrieve the transcript and detailed metadata for a specific phone call. Use when you need to access call recordings, transcripts, duration, or telephony details for a completed call.
  - body: { call_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/contact` — Tool to retrieve details of a specific contact by its ID. Use when you need to fetch contact information.
  - body: { contact_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/knowledge/base` — Tool to retrieve details of a specific knowledge base by its ID. Use after confirming the knowledge base ID to fetch its metadata.
  - body: { knowledge_base_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/memory/store` — Tool to retrieve details of a specific memory store by its ID. Use when you need to fetch metadata and configuration of an existing memory store.
  - body: { memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/memory/store/contact/data` — Tool to retrieve memory data for a specific contact in a memory store. Use when you need to fetch stored memory information associated with a particular contact.
  - body: { contact_id: string, memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/numbers` — Tool to retrieve a list of phone numbers associated with a workspace. Use when you need to fetch numbers assigned to your account for a given workspace.
  - body: { limit?: integer, offset?: integer, workspace: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/simulation` — Tool to retrieve details of a specific simulation by ID. Use to fetch simulation results including timeline, recording, and success criteria evaluation after a simulation has been executed.
  - body: { simulation_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/simulation/case` — Tool to retrieve a simulation case by ID. Use when you need to fetch details of a specific simulation case including its prompt, success criteria, and metadata.
  - body: { simulation_case_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/simulation/scenario` — Tool to retrieve a simulation scenario by ID. Use when you need to fetch details of a specific simulation scenario template.
  - body: { scenario_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/simulation/suite` — Tool to retrieve a simulation suite by ID. Use when you need to fetch details about a specific simulation suite including its test cases and associated agent information.
  - body: { suite_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/subaccount` — Tool to retrieve detailed metadata about a specific subaccount by ID. Use when you need to fetch subaccount information including permissions, subscription details, and members.
  - body: { subaccount_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/get/team` — Tool to retrieve details of a specific team by its ID. Use after confirming the team exists to inspect its configuration.
  - body: { team_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/initialize/action` — Tool to initialize a custom action with specified variables. Use when you have an action ID and need to initialize it with configuration variables.
  - body: { action_id: string, variables?: object[] }
- `POST https://api.mcp.ai/api/synthflow_ai/list/actions` — Tool to list all actions in the workspace. Use when you need to retrieve a paginated list of available actions and their configurations.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/synthflow_ai/list/assistants` — Tool to list all AI assistants associated with the account. Use when you need to retrieve a paginated list of assistants.
  - body: { limit?: integer, offset?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/calls` — Tool to retrieve call history (call logs) with filtering to check outcomes/statuses after placing calls. Use after making voice calls to list recent calls for a model, filter by phone number/time wind
  - body: { limit?: integer, offset?: integer, to_date?: integer, model_id: string, from_date?: integer, call_status?: string, duration_max?: integer, duration_min?: integer, lead_phone_number?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/chats` — Tool to retrieve a list of chats, optionally filtered by agent ID. Use when you need to view chat history or check recent conversations.
  - body: { limit?: integer, cursor?: string, agent_id?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/contacts` — Tool to retrieve a list of contacts with optional search filtering. Use when you need to list all contacts or search for specific contacts by phone number.
  - body: { search?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/memory/stores` — Tool to list memory stores with optional filtering by title. Use when you need to retrieve all memory stores in a workspace, optionally filtered by search term.
  - body: { search?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/phone/books` — Tool to list all phone books in your workspace. Use when you need to retrieve all phone books for organizing contacts in Synthflow AI.
- `POST https://api.mcp.ai/api/synthflow_ai/list/simulation/cases` — Tool to list simulation cases with pagination and optional filtering by name or type. Use when you need to retrieve simulation cases for testing agent behavior.
  - body: { search?: string, page_size?: integer, page_number?: integer, simulation_case_type?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/simulation/cases/by/agent` — Tool to list all simulation cases created for a specific agent. Use when you need to retrieve test scenarios associated with a particular agent ID.
  - body: { agent_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/simulation/scenarios` — Tool to list simulation scenarios with pagination and optional filtering. Use when you need to retrieve simulation scenario templates with support for search by name and date range filtering.
  - body: { search?: string, end_date?: string, page_size?: integer, start_date?: string, page_number?: integer }
- `POST https://api.mcp.ai/api/synthflow_ai/list/simulation/sessions` — Tool to list simulation sessions with pagination and optional filters. Use when you need to retrieve simulation sessions, optionally filtered by target agent, date range, or paginated results.
  - body: { end_date?: string, page_size?: integer, start_date?: string, page_number?: integer, target_agent_id?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/simulation/suites` — Tool to list simulation suites with pagination and optional filtering. Use when you need to retrieve simulation suites, optionally filtered by model IDs, date range, or search term.
  - body: { search?: string, end_date?: string, model_ids?: string[], page_size?: integer, start_date?: string, page_number?: integer }
- `POST https://api.mcp.ai/api/synthflow_ai/list/simulations` — Tool to list simulations with pagination and optional filters. Use when you need to retrieve simulation records, optionally filtered by session ID, status, date range, or target agent.
  - body: { status?: string, end_date?: string, page_size?: integer, start_date?: string, page_number?: integer, target_agent_id?: string, simulation_session_id?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/subaccounts` — Tool to list all subaccounts associated with the authenticated account. Use when you need to retrieve all subaccounts and their configurations.
- `POST https://api.mcp.ai/api/synthflow_ai/list/teams` — Tool to list assistant teams. Use when you need to retrieve all teams in a workspace.
- `POST https://api.mcp.ai/api/synthflow_ai/list/voices` — Tool to list all text-to-speech voices in a workspace. Use when you need to retrieve voices available for TTS in a given workspace.
  - body: { limit?: integer, offset?: integer, workspace: string }
- `POST https://api.mcp.ai/api/synthflow_ai/list/webhook/logs` — Tool to retrieve paginated webhook logs with filtering and search capability. Use when you need to audit webhook delivery, check webhook statuses, troubleshoot failed webhooks, or search for specific 
  - body: { search?: string, status?: string, call_id?: string, to_date?: string, from_date?: string, page_size?: integer, http_method?: string, page_number?: integer, assistant_id?: string, webhook_type?: string, workspace_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/make/voice/call` — Tool to initiate a real-time voice call via the AI agent. Use when you have the agent ID, customer name, and phone number ready.
  - body: { name: string, phone: string, prompt?: string, greeting?: string, model_id: string, lead_email?: string, lead_timezone?: string, custom_variables?: object[] }
- `POST https://api.mcp.ai/api/synthflow_ai/start/simulation` — Tool to start a new simulation using a simulation case. Use when you need to execute a test scenario against an agent to validate its behavior and performance.
  - body: { target_agent_id: string, custom_variables?: object, simulation_case_id: string, simulation_session_id?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/update/action` — Tool to update an existing action in Synthflow AI. Use when you need to modify an action's configuration such as real-time booking, information extraction, live transfer, SMS sending, custom HTTP call
  - body: { SEND_SMS?: object, action_id: string, CUSTOM_EVAL?: object, CUSTOM_ACTION?: object, LIVE_TRANSFER?: object, REAL_TIME_BOOKING?: object, INFORMATION_EXTRACTOR?: object }
- `POST https://api.mcp.ai/api/synthflow_ai/update/assistant` — Tool to update an existing assistant’s settings. Use after confirming the assistant exists. Modify settings like name, phone, recording, webhook, or agent configuration.
  - body: { name?: string, agent?: object, assistant_id: string, consent_text?: string, is_recording?: boolean, max_duration?: object, phone_number?: string, caller_id_number?: string, consent_recording?: boolean, external_webhook_url?: string, is_transcript_disabled?: boolean }
- `POST https://api.mcp.ai/api/synthflow_ai/update/contact` — Tool to update an existing contact in Synthflow AI. Use when you need to modify contact details like name, phone, email, or metadata.
  - body: { name?: string, email?: string, contact_id: string, phone_number?: string, contact_metadata?: object }
- `POST https://api.mcp.ai/api/synthflow_ai/update/knowledge/base` — Tool to update an existing knowledge base's name or usage conditions. Use after confirming the knowledge base exists.
  - body: { name?: string, knowledge_base_id: string, rag_use_condition?: string }
- `POST https://api.mcp.ai/api/synthflow_ai/update/memory/store` — Tool to update an existing memory store's title and description. Use when you need to modify metadata of a memory store.
  - body: { title?: string, description?: string, memory_store_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/update/simulation/case` — Tool to update an existing simulation case. Use when you need to modify the name, prompt, success criteria, or evaluation method of a simulation case.
  - body: { name?: string, prompt?: string, success_criteria?: string[], call_success_type?: string, simulation_case_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/update/simulation/scenario` — Tool to update an existing simulation scenario. Use when you need to modify the name or description of a scenario template.
  - body: { name?: string, description?: string, scenario_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/update/simulation/suite` — Tool to update an existing simulation suite. Use when you need to modify the name or agent model of a simulation suite. At least one of name or model_id must be provided.
  - body: { name?: string, model_id?: string, suite_id: string }
- `POST https://api.mcp.ai/api/synthflow_ai/update/team` — Tool to update an existing team. Use after confirming the team exists and you have new configuration values.
  - body: { name?: string, team_id: string, phone_number?: string, external_webhook_url?: string, sub_assistants_attach?: object[], sub_assistants_detach?: object[] }

## Example prompts
- "What can I do in Synthflow AI?"
- "Show me a summary of my Synthflow AI account"

## More
- Page: https://mcp.ai/synthflow_ai
- Agent spec (llms.txt): https://mcp.ai/synthflow_ai/llms.txt
- Postman collection: https://mcp.ai/synthflow_ai/postman.json