Trellus MCP documentation

Connect your AI assistant

Copy the exact server URL above. Keep the /rpt/mcp path and do not add a trailing slash. In a managed workspace, an administrator may need to allow custom connectors.

Ask a question that you can check

Start with a time range and a specific metric. The assistant should discover your account settings first, then report the filters and timezone it used.

Use Trellus to get my team’s reporting timezone. For the last seven complete days, show outbound dial attempts, connected calls, and total live duration by rep. Include unanswered attempts in total dials and use rep names instead of IDs.

Use Trellus to compare the last 30 days by disposition. Show session count and total duration, then calculate average duration. Explain which filters you used.

Use Trellus to find five calls in the last seven days with the fields needed to identify them. Open one selected session and summarize its outcome, objections, and next step without including customer contact details.

Tool reference

These are the four hosted Trellus MCP tools. Examples below are tool argument objects; your MCP client sends them through tools/call. Extra arguments are rejected.

{}

{
  "cnf": [
    [
      {
        "column_name": "conversation_type",
        "operator": "EQ",
        "value_safe": 1
      }
    ]
  ],
  "select": [
    "session_id",
    "started_at",
    "resource_id",
    "duration",
    "dial_metric.is_inbound",
    "user_log.disposition"
  ],
  "limit": 5,
  "redact_phone_numbers": true
}

{
  "cnf": [
    [
      {
        "column_name": "dial_metric.is_dial",
        "operator": "EQ",
        "value_safe": true
      }
    ],
    [
      {
        "column_name": "dial_metric.is_inbound",
        "operator": "EQ",
        "value_safe": false
      }
    ]
  ],
  "selects": [
    {
      "cnf": []
    },
    {
      "cnf": [
        [
          {
            "column_name": "dial_metric.is_connected",
            "operator": "EQ",
            "value_safe": true
          }
        ]
      ]
    },
    {
      "column_name": "dial_metric.live_duration"
    }
  ],
  "group_by": {
    "column_name": "resource_id"
  }
}

{
  "session_id": "SESSION_ID_FROM_SEARCH",
  "redact_phone_numbers": true
}

[
  "session_id",
  "started_at",
  "conversation_type",
  "resource_id",
  "duration",
  "dial_metric.is_inbound",
  "dial_metric.sip_code",
  "customer_data.name",
  "customer_data.company_name",
  "user_log.disposition",
  "user_log.sentiment",
  "user_log.purpose"
]

Filters and breakdowns

Use cnf to describe which sessions match. An empty array selects all sessions within the time range and the account’s permitted scope.

• Each filter has column_name, operator, and value_safe. Use a reporting column published in tools/list, or a supported field under state.* or custom_metrics.*.
• Outer cnf groups are joined with AND. Filters inside one group are joined with OR. Empty cnf means no extra filters.
• EQ and NEQ compare scalar values, including null. IN and NIN take arrays of up to 1,000 values; null is not accepted in these arrays.
• GT, GE, LT, and LE compare numeric or string columns. REGEX is available for strings and supported dynamic fields, with patterns up to 512 characters.
• Boolean, byte, and enum fields support EQ, NEQ, IN, and NIN. Numeric fields additionally support ordering. Enum values must match the published name or number.
• For a column inside a list, such as agents[*].agent_id, add reducer: "ANY" or "ALL". Do not add a reducer to a scalar column.
• Use at most 100 outer groups and 20 filters per group. Unknown fields, unsupported operators, extra arguments, and invalid filter or value types return a tool error.

[
  [
    {
      "column_name": "dial_metric.is_inbound",
      "operator": "EQ",
      "value_safe": false
    }
  ],
  [
    {
      "column_name": "agents[*].agent_id",
      "operator": "EQ",
      "value_safe": "REP_ID_FROM_BOOTSTRAP",
      "reducer": "ANY"
    },
    {
      "column_name": "duration",
      "operator": "GT",
      "value_safe": 60
    }
  ]
]

This example means: non-inbound sessions AND either a matching agent OR a duration above 60 seconds. Replace the example rep ID with one returned by trellus_bootstrap.

Group metrics by one dimension

Set group_by.column_name to one of the values below. Grouping is available on trellus_metric_details, not session search.

[
  "agent_joined",
  "agents[*].agent_id",
  "agents[*].agent_type",
  "conversation_type",
  "customer_joined",
  "dial_metric.is_inbound",
  "dial_metric.sip_code",
  "platform",
  "resource_id",
  "user_log.disposition",
  "user_log.purpose",
  "user_log.sentiment"
]

Your MCP client can retrieve the complete accepted reporting-column and enum definitions through tools/list. Use those definitions when generating filters.

Keep reporting definitions consistent

• For calendar dates, obtain team_info.analytics_timezone from trellus_bootstrap and convert the requested local boundaries to Unix microseconds. Ask the user for a timezone if it is unset.
• A dial count should include unanswered attempts. For outbound dials, filter dial_metric.is_dial=true and dial_metric.is_inbound=false, then use { "cnf": [] } as a select. Do not add connection, duration, or disposition filters to the total unless the question asks for them.
• Use a separate filtered select for connected calls. Do not treat agent_joined=false alone as a universal definition of a missed call; combine it with the relevant inbound and call filters.
• Grouping by agents[*] expands a session across its agents, so the same session can contribute to more than one group. Those group totals may not add up to the unique session count.
• MCP query boundaries use microseconds. Reporting started_at values use Unix seconds; duration, connected duration, and live duration are measured in seconds.
• All four tools read data. They do not place calls, edit CRM records, change campaigns, or modify account settings.

For field-level definitions, query recipes, and a direct HTTPS integration, see the Call Data API reference.

OAuth for custom clients

Use the endpoint’s discovery metadata, authorization-code flow, and S256 PKCE. The resource is the full MCP URL. Request only rpt:read and send the resulting OAuth token in the Authorization: Bearer header.

The discovery response provides authorization, registration, token, and revocation endpoints. A client must store each rotated refresh token returned by a successful refresh. Do not expose tokens in browser page source, public repositories, examples, or chat prompts.

The assistant’s runtime may not open the consent window itself. In that case, your application must complete OAuth before handing an access token to the MCP runtime. The read-only OAuth token is different from a Trellus API key.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "trellus_bootstrap",
    "arguments": {}
  }
}

Troubleshooting

Still need help? Contact Trellus support with the client name, the tool name, and any error reference. Keep credentials out of the message.