Skip to main content
Connect your AI agent to Avoca MCP to retrieve call records and metrics. Your agent handles analysis and presentation. These tools read existing data; they do not start an Avo conversation or run an Avo model.
Customer data MCP requires activation by Avoca. If the server reports that it is not enabled, contact your Avoca representative. Your existing dashboard data permissions apply; a workspace Avo flag is not required by this connection.

​
Connect your app

  1. In an MCP client that supports remote Streamable HTTP servers and OAuth, add this server URL:
  2. Follow the client’s sign-in prompt. Sign in to Avoca using your usual dashboard method, including Google when available for your account.
  3. Review the app name, return address, and requested Read Avoca data access. Choose Allow access to connect or Deny to cancel.
  4. Ask your agent to list your team workspaces, then retrieve data from the workspace you select.
Example app requesting read-only Avoca data access The connection follows your current permissions across teams and enterprises. Call transcripts may contain personal information. Only approve apps you trust with the data they can read. Signing in does not add workspace membership or grant additional permissions. You do not need to copy a dashboard token or create an Enterprise API key. Your dashboard sign-in stays the same; the connected app receives a separate credential for this MCP. The connection is separate from Avoca’s internal staff MCP. For custom MCP clients, the OAuth scope is avoca:read. Send one refresh request at a time and save the replacement refresh token before refreshing again. Reusing a refresh token, including simultaneous requests or retries after an uncertain response, revokes the connection and requires reauthorization.

​
Select your data

Call lists, details, and transcripts require team_id and the team’s Calls permission. Details and transcripts also require call_id. Enterprise membership alone does not grant permission to read an individual team’s call records. Metrics take workspace_type (team or enterprise), workspace_id, date_from, and date_to. Team metrics require the team’s Calls permission; enterprise metrics require the enterprise Calls permission and are limited to 50 accessible teams. The start timestamp is inclusive and the end timestamp is exclusive; timestamps are not rounded to calendar days. The response includes source: "clickhouse", the requested dates, team_count, and a metrics array. Each metric contains metric_id, name, unit, and value. Available metrics are Total Calls, Total Duration (seconds), Leads, Booked Calls, Unbooked Calls, Transferred Calls, Contained Booked Calls, and Contained Leads. They reuse the dashboard’s standard metric definitions and the Custom Analytics visible-call population, including human-handled and unprocessed calls. A Calls page with additional filters can show different totals. Lead, booking, and transfer metrics overlap; do not add them to calculate total calls. Recent changes can take time to reach ClickHouse. Metrics are unavailable through MCP for workspaces whose call classifications are not yet supported by the ClickHouse analytics compiler. If any accessible team in an enterprise is unsupported, the whole enterprise query fails; it does not return a partial total. Use dashboard analytics or select a supported team in that case. You can also use the numeric workspace ID from a dashboard URL:
  • Team: https://dashboard.avoca.ai/team/TEAM_ID
  • Enterprise: https://dashboard.avoca.ai/enterprise/ENTERPRISE_ID
Workspace discovery is bounded and may omit workspaces available through other access paths. A parent enterprise ID in a team result does not imply enterprise membership. If a workspace is missing, provide its known dashboard ID; permissions are checked when data is requested.

​
Keep requests focused

  • Call lists and metrics require ISO timestamps with a timezone offset and a date range of at most 31 days. For example, 2026-09-01T00:00:00Z to 2026-09-08T00:00:00Z.
  • Call lists return 20 records by default, up to 100. Filter with is_booked, is_bookable, is_transferred, call_reasons, or call_outcomes.
  • Pass next_cursor back as cursor to continue a call list, keeping the same team, dates, and filters. Stop when has_more is false. The tools never download every page automatically.
  • Transcripts return up to 8,000 characters by default, with a maximum of 20,000. Pass transcript.nextCursor as cursor while transcript.hasMore is true.
  • Workspace discovery uses offset and limit, returning pageInfo.nextOffset while more results are available.
  • Prefer metrics for aggregate questions. Fetch individual transcripts only when needed. A failed metrics query is reported as unavailable, not as a zero count.
Example request to your agent: “For this team, find up to 20 transferred calls from September 1–7, then retrieve the transcript for the call I select.” The MCP cannot modify records, approve actions, or retrieve arbitrary database queries. It returns structured data that your agent can use to build its own tables or charts.

​
Disconnect an app

Open Connected apps while signed in to Avoca, then choose Disconnect beside the app. Removing the server from your MCP client alone may leave its authorization active. Disconnecting stops new MCP requests and leaves your dashboard sign-in active. Connections expire after 30 days; reconnect through the sign-in and approval flow. Connected apps with a Disconnect button

​
Troubleshooting

  • Sign-in keeps failing: Restart the connection in your MCP client. Use the Avoca account with access to the intended workspace.
  • Data access is denied: Verify your team or enterprise membership and the applicable Calls permission. Access to enterprise metrics does not necessarily include individual team records.
  • Metrics unavailable: Use dashboard analytics if your workspace is not yet supported. For a timeout or query limit, narrow the date range or select one team. Failed or incomplete queries never return a zero count as a substitute.
  • Invalid query: Check the date range, workspace ID, and cursor. Enterprise metrics support at most 50 accessible teams; use individual team metrics for larger enterprises.
  • Too many concurrent requests: Reduce parallel reads and retry after the delay indicated by the server.
  • The app requires a client secret: This integration supports public OAuth clients with PKCE. Use a client that supports that flow.