Overview
Bananaflow runs an MCP (Model Context Protocol) server. Connect it to Claude Code, Claude Desktop, Cursor, Codex or any other MCP client, and your assistant can build voice agents for you, end to end. Once connected, your assistant can:- Create and edit agents. It writes the agent as code, saves it, and edits it later.
- Add tools and integrations. HTTP APIs, call transfers, calculators, MCP servers, and ready-made actions in products you have connected, such as HubSpot or Gmail.
- Set the voice and how the agent takes turns. Pick a voice and languages, tune when the agent replies or lets the caller interrupt, and add hard words to the Dictionary.
- Test the agent. Chat with it by text, write and run evals, run voice simulations, and place a real test call to your phone.
- Publish and manage versions. Publish a draft when you say so, roll back to an old version, copy agents and sort them into folders.
- Run phone numbers and campaigns. Pick which agent answers a number, and set up, start and pause calling campaigns.
- Manage content. Add knowledge base documents and recordings, and check your usage and reports.
- Read your calls. List recent calls, read their transcripts and see each call’s details.
- Search the Bananaflow docs while it works.
Prerequisites
- A Bananaflow API key. Generate one at
/api-keys. See API Keys. - Your Bananaflow MCP endpoint:
https://app.bananaflow.ai/api/v1/mcp/
X-API-Key header. If your client can only send an Authorization header, Authorization: Bearer YOUR_API_KEY works too.
Claude Code
Register Bananaflow as an MCP server with the Claude Code CLI:YOUR_API_KEY with the key you generated.
Verify the server is connected:
Codex
Open Codex’s config file (~/.codex/config.toml) and add a bananaflow MCP server:
YOUR_API_KEY with the key you generated.
If you prefer to keep the API key out of config.toml, store it in an environment variable instead:
Claude Desktop
Open Claude Desktop’s config file (claude_desktop_config.json) and add the bananaflow entry under mcpServers:
Cursor and other MCP clients
Any MCP client that supports Streamable HTTP transport can connect with the same URL and header. Paste the configuration above into your client’s MCP settings file and replaceYOUR_API_KEY.
Try it
Paste one of these into Claude Code or Cursor once the server is connected:- “Create an inbound appointment-booking agent for my dental clinic. It speaks Hindi and English and starts in English. Pick a female voice that speaks both. Then test it by text chat: book a cleaning for Saturday morning.”
- “In my Lead Qualifier agent, add a HubSpot tool that creates a contact with the caller’s name and phone number, and call it once the caller is qualified. Save the change.”
- “Write three evals for Lead Qualifier: a caller who shares a budget, a caller who refuses to, and a caller who asks for a human. Run them, and fix the agent where it fails.”
- “Read the transcripts of the last five calls to Support Bot that lasted over a minute. Tell me where callers got stuck, and add any brand or place names it misheard to its Dictionary.”
- “List my agents in Bananaflow.”
- “Make Support Bot wait a little longer before it replies.”
- “My Check order tool should say ‘One moment, checking your order’ before it runs. Change its start message.” Your assistant finds the tool with
list_toolsand callsupdate_toolwith a newcustom_message. Every agent that uses Check order says the new line from the next call. - “What node types does Bananaflow support, and what fields does an
agentNodetake?” - “The evals for Support Bot pass. Publish it.” Your assistant calls
publish_workflow, and real callers get the new version from the next call. It publishes only when you ask. - “Call my phone, +91 98765 43210, with the Support Bot draft so I can hear it.” Your assistant tells you it will dial that number and what a call costs, then calls
place_test_call. When you hang up, it reads the call back withget_call_transcript. - “Show me the details of my last call to Lead Qualifier.” Your assistant finds it with
list_callsand callsget_callfor the numbers, length, outcome, what the agent collected, and links to the recording and transcript.
Tools
These are the tools your assistant sees, grouped by job. Your assistant picks them for you; you rarely need to name one.Build
get_voice_prompting_guide– the build process and voice-prompting guide; assistants read it before writing an agent.list_node_types– every node type, with a short summary.get_node_type– the full schema and examples for one node type.create_workflow– create a new agent from SDK code, with an optional voice and languages.list_workflows– list your agents.get_workflow– read one agent as SDK code, with its name, status and version.get_workflow_code– read an agent’s SDK code to edit it.save_workflow– save edited SDK code as the agent’s draft.generate_examples– start writing the example lines for one node’s prompt.get_generated_examples– check on examples started withgenerate_examples.list_credentials– list saved credentials for webhooks and pre-call data fetch.
Publishing and versions
publish_workflow– makes your saved changes live, so real calls use them. Your assistant runs it only when you ask.list_workflow_versions– shows every version of an agent, newest first, with its notes.restore_workflow_version– copies an old version’s prompts back into the draft. You still publish to make it live.duplicate_workflow– makes a copy of an agent, with an optional new name.set_workflow_status– archives an agent, or brings an archived one back.list_folders– lists your folders and how many agents are in each.create_folder– makes a new folder to group your agents.move_workflow_to_folder– puts an agent in a folder, or takes it out.get_web_widget– shows if the website widget is on, and gives the code to paste.set_web_widget– turns the website widget on or off and sets which sites can use it.
Tools and integrations
list_tools– list the tools in your workspace.create_tool– create a tool: HTTP API, end call, transfer call, transfer agent, calculator, MCP or reasoner.update_tool– edit an existing tool’s name, description, start message (custom_message) or preset arguments (integration tools only). For an HTTP tool it also changes the URL, method, headers, parameters and credential (http_config).test_tool– sends one real request with sample values, so you can see if an HTTP tool works before an agent uses it.archive_tool– takes a tool out of use. Agents that list it stop getting it on their next call. You can bring it back.unarchive_tool– brings an archived tool back, so agents that list it get it again.refresh_mcp_tool– asks an MCP server for its current list of tools and saves it.search_integrations– find a ready-made action in a third-party product, such as “hubspot create contact”.create_integration_tool– add an action found bysearch_integrationsas a tool.list_integration_connections– list the third-party products your workspace has connected.
Voice and turn-taking
list_voices– list the voices you can give an agent, filtered by language, gender or free text.get_agent_voice– read an agent’s voice and languages.set_agent_voice– set an agent’s voice, its languages and the language each call starts in.get_turn_settings– read an agent’s turn rules and its interruption and end-of-turn judges.set_turn_settings– change when the caller can interrupt, when their turn ends, and how eagerly the agent replies.set_end_turn_judge– turn the end-of-turn judge on or off and tune how long it waits.get_dictionary– read the words speech-to-text listens for.set_dictionary– replace the agent’s Dictionary with a new word list.
Test and evaluate
start_text_chat– start a text chat with an agent and get its opening line.send_text_chat_message– send one caller message and get the agent’s reply.rewind_text_chat– takes a test chat back to an earlier turn, so you can try a different caller line.end_text_chat– end a text chat and read what the agent extracted.get_eval_options– list the nodes, tools and default judge prompt an eval can use.list_evals– list an agent’s saved evals with their latest run.create_eval– save an eval: a scripted conversation with checkpoints.update_eval– replace a saved eval with a new version.delete_eval– deletes an eval and all its past runs. This cannot be undone.run_eval– start a run of a saved eval against the agent’s draft.get_eval_run– check on an eval run and read its result.list_eval_runs– shows an eval’s past runs, newest first, with pass or fail.
Voice simulations
get_simulation_setup– see everything you can use to voice-test an agent: testers, scenarios, simulations, suites and the agent’s tools.save_simulation_personality– create or change an AI tester: how it acts, sounds and listens.save_simulation_scenario– create or change a test: what the tester tries to do and how the call is graded.generate_simulation_scenarios– ask AI to suggest tests for your agent. It saves nothing and costs a little credit.save_simulation– pair one scenario with one tester to make a simulation.save_simulation_suite– group simulations so they run together.delete_simulation_part– delete a tester, scenario, simulation or suite you own.run_simulations– start real voice test calls to your agent. Each call is billed like a normal call.get_simulation_run– check a test run, or read one call’s transcript and grades.cancel_simulation_run– stop a test run.
Calls and phone numbers
list_calls– list an agent’s completed voice calls, newest first.get_call_transcript– read the transcript of one call.get_call– shows one call’s details: numbers, length, outcome, what was collected, and links to the recording and transcript.list_phone_numbers– shows your phone numbers and which agent answers each one.list_telephony_configs– shows your phone setups and whether each can make calls. It never shows passwords or keys.set_phone_number_agent– picks which agent answers calls to a number, or takes the agent off.place_test_call– calls a real phone with your agent’s draft so you can hear it. It costs money like any call.
Campaigns
list_campaigns– see all your calling campaigns and how far each one has got.get_campaign– look at one campaign: its settings, live progress and log.create_campaign– make a new calling campaign from a list of people to call. It does not call anyone yet.update_campaign– change a campaign’s name, calling hours, speed or retry rules.set_campaign_state– start, pause or resume a campaign. Start and resume make real, paid calls.redial_campaign– make a new campaign that calls back the people a finished campaign missed. Each campaign can be redialed only once.get_campaign_report– get a campaign’s call results as a spreadsheet (CSV).
Usage and reports
get_usage– see this period’s call minutes and your credit balance.get_usage_history– list your calls with how long they ran and what they cost.get_report_summary– get the Reports page numbers for a date range: calls, success rate, outcomes, busy hours.
Knowledge base and recordings
list_documents– list knowledge-base documents a node can use.create_document_from_text– adds a knowledge document from text or Markdown your assistant already has.get_document_upload_url– gives a one-time link to upload a file, like a PDF, as a knowledge document.add_document– saves the file you just uploaded as a knowledge document and starts reading it.get_document– shows one document’s status and, for text files, what it says.update_document_content– replaces the text of a .md or .txt document and reads it again.delete_document– deletes a knowledge document. Agents stop using it right away.search_documents– searches your documents the same way an agent does on a call.list_recordings– list pre-recorded audio for greetings and transition speech.get_recording_upload_url– gives a one-time link to upload an audio clip for your agent.add_recording– saves the audio you just uploaded, with what it says, as a recording.update_recording– renames a recording’s short name and updates prompts that use it.delete_recording– deletes a recording. Greetings still set to it go silent, so change them first.
Docs
search_docs– search the Bananaflow docs.list_docs– browse the docs by section.read_doc– read one docs page.
What to know
- Drafts.
save_workflow,restore_workflow_version,set_agent_voice,set_turn_settings,set_end_turn_judgeandset_dictionarysave to the agent’s draft. Your published agent keeps serving calls until the draft is published, either bypublish_workflowwhen you ask your assistant to publish, or from the Bananaflow app. - Real calls only when you ask.
place_test_call, starting or resuming a campaign withset_campaign_state, andrun_simulationsplace real, billed calls.redial_campaigncan be done only once per campaign. Your assistant says what it will dial or cost and runs these only when you ask. - Test calls run the draft.
place_test_calluses the agent’s saved draft, so you can hear a change before you publish it. Inbound and campaign calls run the published version. - New agents go live at once.
create_workflowpublishes the new agent as version 1. Later edits go to a draft. - Tool edits go live at once.
update_tool,archive_toolandunarchive_toolchange the tool for every agent that uses it, published versions included, from the next call. There is no draft step. For example, you rename your Check order tool, and every agent that uses it sees the new name on its next call. - Text chat and evals test text only. They run the agent’s saved draft with no speech-to-text, no voice and no turn timing. They show what the agent says and which tools it calls, not how it sounds.
- Credit. Text chats, eval runs, voice simulations, test calls and example writing use your account’s credit. If you are out of credit or billing is paused, the tool refuses and your assistant tells you. Recharge on the Billing page.
- Integrations need a connection. An integration action works only for a product you have connected in the Bananaflow app.
- Own model providers. If your organization runs its own model providers, the assistant cannot set a Bananaflow voice, and a save that puts a reasoner tool on one of its agents is refused.
The API key controls which workspace the assistant sees and changes. Treat it like any other credential – do not commit it to source control or paste it into shared chats.