eqho

Disconnect and end your current session. This will: - End your current session - Clean up session resources - Clear your connection context After disconnecting, you'll need to call connect() again to use other tools. Returns: Confirmation of disconnection Examples: # End your session disconnect()

Discover what this EQHO MCP server can do. This is the recommended first call when connecting to the EQHO platform. It returns capabilities, **how to navigate EQHO** (connect → context → switch organization → data tools), and connection instructions. The discovery tool will: - Show you what features are available - Include a **navigation** section: org switching, get_context, switch_organization - Explain how to connect and get started - Provide quick start workflows for common tasks Args: query: Optional natural language query to filter capabilities. Examples: "How do I make calls?", "campaign management", "reporting and analytics" Returns: System capabilities, connection instructions, and getting started guide Examples: # Discover everything await discover_capabilities() # Specific capability await discover_capabilities(query="How do I access call recordings?")

Get one agent's full config: voice, personality, greetings, roles, actions, scripts, feature flags. Args: agent_id: Agent ID (from list_agents). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Get one call. summary: status, duration, disposition, numbers. core: the full call record. full: adds the transcript turns and the recording URL (long calls = large response; page the transcript with transcript_offset/transcript_limit). Args: call_id: Call ID (from list_calls). detail: summary | core | full. transcript_offset: First transcript turn to include (full only). transcript_limit: Max transcript turns to include (full only). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Get the QA scorecard for a call: every grader's pass/fail, score and reasoning, plus the overall pass rate (empty when nothing graded yet). Args: call_id: Call to grade-check. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Get one campaign: agents, phone numbers, dispositions, call window, tasks. Args: campaign_id: Campaign ID (from list_campaigns). detail: summary (id, name, status, agents, phone numbers), core (adds dispositions, call_window, rules, lead lists), full (everything incl. tasks and SIP config; large). fields: Explicit top-level fields to return instead of a tier (id/name always kept), e.g. ["tasks", "pre_call_tasks"]. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Get your current session context and connection state. Use this to understand: - Which organization you're currently working with - Your permissions and capabilities - Connection health and status - Session expiration time - Available organizations you can switch to This is helpful when you're unsure about your current context or need to verify which organization's data you're accessing. Args: include_health: Include connection health metrics (default: True) Returns: Current session state, active organization, and connection info Examples: # Check current context get_context() # Quick check without health metrics get_context(include_health=False)

Org-wide or per-campaign performance: dashboard widgets, KPIs, disposition breakdown, duration distribution, call volume. KPIs and per-campaign dashboards default to total_conversations and contact_rate. Override with filters.metrics; query_metrics() lists the available metric IDs. Date bounds are inclusive start, exclusive end. Args: campaign_id: Scope to one campaign (per-campaign performance). start_date: ISO datetime lower bound. end_date: ISO datetime upper bound. view: dashboard (default) | kpis | disposition | duration | call_count. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed. filters: Escape hatch: extra query params forwarded as-is.

Get one lead in full, by ID or by phone/email lookup: names, timezone, custom_fields (CRM ids), extracted_data. This is how a call becomes a person: calls carry lead_id only. phone/email lookup currently goes through the grouped search adapter (GET /v1/leads); routing through GET /v1/leads/lookup lands in EMCP-206 (docs/parity-matrix.md row 39). Args: lead_id: Lead ID (takes precedence). phone: Look up by phone number (E.164). email: Look up by email. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Get one role's full instructions (can be 10K+ words). Args: role_id: Role ID (from list_roles or get_agent). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Get help and guidance based on your current context. This tool provides intelligent assistance by understanding where you are in your workflow and what you're trying to accomplish. It adapts its responses based on: - Whether you're connected - Which organization you're in - What tools you've recently used - Common next steps for your current state Args: topic: Specific topic or question (optional) Examples: "campaign management", "call recordings", "how do I switch organizations?" context_aware: Provide context-specific help (default: True) Returns: Relevant guidance, examples, and next steps Examples: # General help based on current state help() # Specific topic help(topic="How do I analyze campaign performance?") # Get all available topics help(context_aware=False)

Build, edit, and publish IVR phone menus for the active org. **Session Required:** Call ``connect()`` first. Flows are scoped to the active organization. Pass ``org_id`` to scope one call to another org you can access (superadmins: any org); the session's active org is not changed. **Draft vs live:** ``list`` / ``get`` / ``create`` / ``update`` only touch drafts. The call runtime always resolves the latest *published* snapshot, so draft edits never change what a caller currently hears. **Publish rule (mandatory):** ``action="publish"`` changes live behavior. Agents MUST ask the user for explicit approval first, then retry with ``confirm=True``. Session ``always_approve`` does **not** bypass this gate. Calling publish without confirm returns ``ConfirmationRequired`` (no API call is made). Common Workflows ---------------- - See what phone menus an org already has:: ivr_flows(action="list") - Author a draft, ask the user, then publish:: ivr_flows(action="create", data={...}) # ask user: "Publish flow X on org Y?" ivr_flows(action="publish", flow_id="...", confirm=True) Available Actions ----------------- - list: All IVR flows for the active org. Endpoint: GET /v1/ivr-flows - get: One flow, including its full node tree. Endpoint: GET /v1/ivr-flows/{flow_id} - create: New draft flow. Requires ``data``. Endpoint: POST /v1/ivr-flows - update: Edit an existing draft. Requires ``flow_id`` + ``data``. Endpoint: PUT /v1/ivr-flows/{flow_id} - publish: Snapshot the draft for live callers. Requires ``flow_id`` + ``confirm=True``. Endpoint: POST /v1/ivr-flows/{flow_id}/publish Flow Shape ---------- ``data`` is a node tree. Node types must be one of: menu, play, gather, schedule, route, voicemail, submenu, hangup. {"name": "Main Line", "entry_node_id": "greeting", "nodes": {"greeting": {"id": "greeting", "type": "play", "prompt_text": "Thanks for calling.", "next_node_id": "menu"}, "menu": {"id": "menu", "type": "menu", "prompt_text": "Press 1 for sales.", "digit_map": {"1": "sales"}}, "sales": {"id": "sales", "type": "route", "route": {"kind": "ai_agent", "campaign_id": "..."}}}} Examples -------- - ivr_flows(action="list") - ivr_flows(action="get", flow_id="507f1f77bcf86cd799439011") - ivr_flows(action="create", data={"name": "Main Line", "entry_node_id": "greeting", "nodes": {...}}) - ivr_flows(action="update", flow_id="...", data={"name": "Renamed"}) - ivr_flows(action="publish", flow_id="...", confirm=True) # only after the user said yes

List the AI agents in the active org (name, voice, status), paginated. Args: limit: Max agents to return (upstream default ~16, up to 500). skip: Agents to skip (pagination). name: Case-insensitive substring filter on the agent name. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

List calls with server-side filters (summarized rows). Use hours=24 for "what happened today"; use q for free-text search across transcripts. Args: campaign_id: Filter to one campaign. agent_id: Filter to one agent. lead_id: All calls for one lead. call_type: inbound or outbound. start_date: ISO datetime lower bound on call start. end_date: ISO datetime upper bound on call start. hours: Convenience: calls that started in the last N hours (sets start_date when start_date is omitted). q: Free-text search across transcript, greeting and summary. limit: Rows per page (max 500). page: Page number, 1-based. order_by: asc or desc on start time (default desc). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed. filters: Escape hatch: extra query params forwarded as-is.

Pre-call and post-call tasks (webhooks, http_request, email, SMS, call_forward, try_again) configured on a campaign, with their ids. Read-only; call this before update_campaign_tasks. Args: campaign_id: Campaign whose tasks to list. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

List the campaigns in the active org (summarized rows). Args: status: Filter by status: ACTIVE, PAUSED, CREATED, INACTIVE, PROCESSED. Use status="ACTIVE" for "what is running right now". limit: Rows to return. skip: Rows to skip (pagination). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed. filters: Escape hatch: extra query params forwarded as-is.

The disposition_level_3 values actually stored on calls, verbatim, with call counts; plus variant_groups (the same disposition under several spellings) and calls_without_a_disposition. Call this before filtering by disposition: the filter is an exact string match and a guessed value returns zero rows, not an error. Read-only. Args: campaign_id: Restrict to one campaign. start_date: ISO datetime lower bound (default: the last 90 days). end_date: ISO datetime upper bound. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Lead lists in the org, or one list in full when list_id is given. Read-only. Args: list_id: Return this one list. campaign_id: Lists attached to this campaign. q: Name search. unassigned: Only lists not attached to any campaign. limit: Rows per page. page: Page number, 1-based (sent as the API's offset). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

List or search leads (GET /v1/leads). With list_id: the leads on that lead list. Without: search the org by q / campaign_id / time. For a phone or email lookup use get_lead. Names are genuinely null for leads created by inbound calls; use get_lead for the full record (custom_fields, CRM ids). Args: list_id: Lead list to page through. campaign_id: Leads on one campaign. q: Free-text search. start_time: ISO-8601 lower bound on creation time. end_time: ISO-8601 upper bound on creation time. limit: Rows per page. page: Page number, 1-based (sent as the API's ``offset``). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed. filters: Escape hatch: extra query params forwarded as-is.

List the numbers the org owns (with campaign assignments). With query, find one owned number by E.164, raw digits, PN-SID or friendly name (superadmins: falls through to other orgs and reports located_in_org). With phone_number_id, get that number's details. Args: query: E.164 ("+17755460621"), digits, PN-SID, or friendly name. phone_number_id: Get one number by id. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed. filters: Escape hatch: extra query params for the listing.

List agent behaviours (roles). A role is the instruction set an agent follows: who it is, what it knows, how it handles the conversation. Args: limit: Rows to return. skip: Rows to skip. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

List the voices available to agents (voice_audio_id for create_agent). Args: org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Show your MCP role, what it lets you do, and any pending access request. New users start as **viewer** (read-only). Accounts outside @eqho.ai are limited to the production environment. To get more, call request_access. Common Workflows: 1. Hit a ScopeError → my_access() → request_access(role=...) Available Actions: (none - this tool takes no parameters) Examples: my_access()

Aggregated analytics from the v2 reporting endpoint: credit usage, conversations, conversion/contact rates, latency, talk-time and silence metrics, by campaign / agent / disposition / medium / call type and over time. Read-only. With no metrics it returns the catalogue of metric IDs this org can query (including custom metrics); unknown IDs are rejected. Args: metrics: Metric IDs, e.g. ["total_credits_spent", "total_conversations", "conversion_rate", "contact_rate"]. Omit for the catalogue. group_by: campaign | agent | disposition | conversation_medium | call_type. time_granularity: hour | day | week | month | year (omit for one aggregate). range: today | yesterday | last_7_days | last_30_days | last_90_days | this_month | last_month | this_year (default last_7_days). start_date: ISO datetime lower bound (instead of range). end_date: ISO datetime upper bound (instead of range). campaign_ids: Filter to these campaigns. agent_ids: Filter to these agents. disposition_level_3: Exact stored values (see list_dispositions). conversation_mediums: telephony | web_voice | sms | chatbot | email. call_types: inbound | outbound. twilio_statuses: e.g. ["completed"] for completed calls (there is no completion_rate metric). is_dry_run: Include only dry-run (True) or only real (False) calls. trends: Add period-over-period change. summary: Return only the aggregate, dropping time series. top: Cap breakdown rows per bucket. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

IRREVERSIBLE. Releases a number back to the carrier pool; the org loses it and any campaign using it stops dialing/answering on it. Pause and re-point the campaign first. Args: phone_number_id: Owned number id (from list_phone_numbers). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Ask an EQHO administrator for more MCP access than you have now. Files one pending request for your account (a new request replaces an earlier pending one). Nothing changes until an administrator approves it; your access then updates within about a minute. You do not need to reconnect. Roles: viewer Read-only across every tool (default) operator + write on campaigns, calls, agents, leads, content admin Read and write on every tool group platform_admin EQHO staff only custom Exactly the scopes you list Common Workflows: 1. A write returns ScopeError → request_access(role="operator", reason=...) 2. Need a non-production environment → request_access(role="viewer", environments=["prod", "stage"], reason=...) Available Actions: (none - one call files the request) Examples: request_access(reason="Launch weekly outbound campaigns for our team") request_access(role="custom", scopes=["eqho:leads:write"], reason="Upload lead lists only")

Full-text search across what was said on calls (transcript, greeting, summary), server-side. Read-only. text is ANDed token by token with no phrase operator. A row's call_summary often does not contain the term even though the call does; matched_snippet shows the transcript line that hit, so check it rather than trust the summary. Args: text: Words to search for; all tokens must be present. campaign_id: Filter to one campaign. agent_id: Filter to one agent. call_type: inbound or outbound. disposition_level_3: Exact stored values (OR-ed). start_date: ISO datetime lower bound on call start. end_date: ISO datetime upper bound on call start. limit: Rows to return, max 500 (default 25). show_matches: Fetch each returned call's transcript to show the matching line. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Search for organizations by partial or approximate name. Returns ranked fuzzy-match results so you (or the user) can pick the right org before switching. This tool has **no side effects** — it does not change the active organization. Use this when: - The user doesn't know the exact org name or ID - You need to disambiguate between similarly-named orgs - You want to confirm which org to switch to After finding the right org, call switch_organization(org_id='...'). Args: query: Partial or approximate organization name (e.g. "inside real", "IRE", "eqho prod"). Case-insensitive, typo-tolerant. limit: Max results (default 5). Returns: Ranked list of matching organizations with match scores. Examples: search_organizations(query="inside real") search_organizations(query="IRE", limit=3) search_organizations(query="eqho")

Search carrier inventory for numbers available to purchase (US/CA). Read-only; buy one with claim_phone_number. Args: area_code: Preferred area code, e.g. "801" (some have no inventory). carrier: twilio (default) or telnyx; match it on claim. contains: Digit/letter pattern the number must contain. country_code: US or CA. toll_free: Search toll-free (8xx) instead of local. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed. filters: Escape hatch: extra query params (in_region, in_postal_code).

Starts or stops dialing. start/resume begin PAID outbound calls on the campaign's lead lists; pause is reversible; stop ends the campaign. When a client says "stop calls", use pause (reversible), not stop. Args: campaign_id: Campaign to control. status: start | pause | resume | stop. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

PAID. Sends a one-off outbound SMS conversation to one lead now: runs a campaign-rule preflight (status, medium, call window, A2P), finds or creates the lead on lead_list_id, triggers POST /v1/sms-now/sms-lead-now, then checks after verify_after_seconds that a conversation appeared. Use call_now for a voice call. Args: campaign_id: Campaign whose rules and agent apply. lead_list_id: Lead list that receives the lead. phone_number: Lead phone number, E.164. first_name: Optional first name (default "Lead"). last_name: Optional last name. email: Optional email. timezone: IANA timezone used for the call-window check and stored on the lead. extra_data: Custom fields stored on the lead. recall_threshold_in_seconds: Not sent (the SMS endpoint has no such field); reported back. verify_after_seconds: Wait before the post-trigger health check (0-15, default 3). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Switch to a different organization (account). Note: 'Organization' and 'account' are used interchangeably in EQHO. If you have access to multiple organizations (e.g., support agent, consultant, superadmin), use this to switch context. All subsequent tool calls will use the new organization's data. **org_name accepts partial or approximate names** — fuzzy matching is built in. If unsure which org to switch to, call search_organizations(query='...') first for ranked results. Use Cases: - Support agents helping multiple customers - Consultants managing multiple client accounts/organizations - Platform administrators with multi-org access - Agencies working with multiple companies Args: org_id: Organization ID to switch to org_name: Organization name — accepts partial/approximate names (fuzzy matched) list_available: Just list available orgs without switching Returns: New context or list of available organizations Examples: # List available organizations switch_organization(list_available=True) # Switch by ID switch_organization(org_id="65b96d473a1934b055687945") # Switch by name switch_organization(org_name="EQHO Main Account") After Switching: - All tools now use the new organization's data - Use get_context() to verify the switch - You can switch back anytime

Modifies a live agent. Scalar and object fields you omit are preserved; ARRAY fields (action_ids, role_ids, script_ids, data_store_ids, structured_greetings, feature_flags) are REPLACED WHOLESALE, so read the agent first and send the complete array. Covers greeting, system prompt / roles, voice and campaign assignment (assign via update_campaign(data={"agents": [...]}) when the link lives on the campaign). Args: agent_id: Agent to update. data: Only the fields to change. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Overwrites the stored outcome (disposition_level_3) of a call; reports and downstream webhooks see the new value. Args: call_id: Call to relabel. disposition_level_3: New disposition value (exact string as configured; see list_disposition_configs). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Modifies a live campaign. Field-level partial update: top-level fields you omit are preserved; fields you send are REPLACED WHOLESALE, arrays included (sending tasks with 1 task on a campaign with 18 deletes 17). Preview safely with dry_run=True (diffs against the live campaign, writes nothing). To pause calls use set_campaign_status(status="pause"). Args: campaign_id: Campaign to update. data: Fields to change (status, agents, phone_numbers, dispositions, call_window, tasks, custom_fields, inbound_lead_list, ...). dry_run: Diff only, no write. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Overwrites the campaign's ENTIRE tasks array; any existing task you omit is deleted. Refuses a write that would drop existing tasks unless replace_all=True, and lists what it would have deleted. Call list_campaign_tasks first and send back every task with your edit. Args: campaign_id: Campaign to update. tasks: The complete array of task objects (pre_call and post_call). replace_all: True only to intentionally delete tasks not in ``tasks``. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Modifies a role that live agents may already use: the change applies to their next call. Send the complete description; the body is forwarded as-is. Args: role_id: Role to update. data: Fields to change, e.g. {"description": "..."}. org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.

Creates N lead records (one per entry, up to 1000 per call) on a lead list through POST /v1/leads. Every lead becomes dialable by any ACTIVE campaign attached to that list, so upload to a list on a CREATED/PAUSED campaign first. Rows that fail are reported individually; the rest are still created. Args: list_id: Lead list to add the leads to. leads: Lead objects; each needs phone (E.164); first_name, last_name, email, timezone and custom_fields are optional. concurrency: Parallel requests (1-10, default 5). org_id: Optional organization override for THIS call only. Superadmins may target any org; other users only orgs they can access (anything else raises a 403). The session's active org is not changed.