Topline OS MCP — Tool reference

Verify the Topline Private Integration Token works and return basic location info. Call this first to confirm setup.

No parameters.

Example call

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

End-to-end setup verification for Topline MCP. Confirms the Private Integration Token is valid, resolves the location, and probes every major scope (contacts, conversations, opportunities, calendars, workflows, forms, surveys, users, custom fields, tags). Returns a structured pass/fail report so you can guide the user to fix any missing scopes. Call this immediately after a client finishes setup.

No parameters.

Example call

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

Generic passthrough to any Topline API v2 endpoint. Use this when no dedicated tool fits. Provide the path (e.g. "/contacts/" or "/opportunities/pipelines") and HTTP method. If the path or query needs a locationId and you don't provide one, the configured sub-account location is used automatically. Returns the parsed JSON response.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_request",
    "arguments": {
      "method": "GET",
      "path": "string"
    }
  }
}

Search contacts by free-text query (name, email, phone) and/or tag. Returns up to 100 per call with a cursor for pagination.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_search_contacts",
    "arguments": {
      "query": "string",
      "tags": [
        "string"
      ]
    }
  }
}

Fetch a single contact by ID. Returns all standard fields and custom fields.

Parameters

Example call

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

Create a new contact. At minimum provide a name or email or phone. Custom fields go in customFields as {id, value} pairs.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_contact",
    "arguments": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

Update fields on an existing contact.

Parameters

Example call

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

Permanently delete a contact. Irreversible.

Parameters

Example call

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

Add one or more tags to a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_add_contact_tags",
    "arguments": {
      "contactId": "string",
      "tags": [
        "string"
      ]
    }
  }
}

Remove one or more tags from a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_remove_contact_tags",
    "arguments": {
      "contactId": "string",
      "tags": [
        "string"
      ]
    }
  }
}

Create a contact, or update the existing one if email/phone matches. Use this when you're not sure whether the contact already exists.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_upsert_contact",
    "arguments": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

Enroll a contact in a workflow.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_add_contact_to_workflow",
    "arguments": {
      "contactId": "string",
      "workflowId": "string"
    }
  }
}

Remove a contact from a workflow.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_remove_contact_from_workflow",
    "arguments": {
      "contactId": "string",
      "workflowId": "string"
    }
  }
}

List all tasks for a contact.

Parameters

Example call

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

List all notes on a contact.

Parameters

Example call

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

Search conversations for the sub-account. Filter by contact, status, or query.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_search_conversations",
    "arguments": {
      "contactId": "string",
      "query": "string"
    }
  }
}

Fetch a single conversation thread including recent messages.

Parameters

Example call

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

List messages in a conversation.

Parameters

Example call

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

Send a message (SMS, Email, WhatsApp, or Facebook/Instagram DM) to a contact. The contact must already exist.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_send_message",
    "arguments": {
      "contactId": "string",
      "type": "SMS"
    }
  }
}

Create a new conversation with a contact (rarely needed — send_message usually creates one implicitly).

Parameters

Example call

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

List all opportunity pipelines in the sub-account with their stages.

Parameters

Example call

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

Search opportunities. Filter by pipeline, stage, status, contact, or free text.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_search_opportunities",
    "arguments": {
      "query": "string",
      "pipelineId": "string"
    }
  }
}

Fetch a single opportunity by ID.

Parameters

Example call

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

Create a new opportunity in a pipeline stage, associated with a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_opportunity",
    "arguments": {
      "pipelineId": "string",
      "pipelineStageId": "string",
      "contactId": "string",
      "name": "string"
    }
  }
}

Update an opportunity — move stages, change value, mark won/lost, etc.

Parameters

Example call

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

Delete an opportunity.

Parameters

Example call

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

List all calendars configured on the sub-account.

Parameters

Example call

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

Get available time slots for a calendar within a date range (ms epoch).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_calendar_slots",
    "arguments": {
      "calendarId": "string",
      "startDate": 0,
      "endDate": 0
    }
  }
}

Book an appointment on a calendar for a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_appointment",
    "arguments": {
      "calendarId": "string",
      "contactId": "string",
      "startTime": "string"
    }
  }
}

Update an appointment (reschedule, change status, reassign).

Parameters

Example call

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

Cancel and delete an appointment.

Parameters

Example call

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

Get the full calendar definition (availability rules, team members, slot duration, etc.).

Parameters

Example call

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

Update a calendar's name, description, slot duration, availability, team members, or event title. Pass only the fields you want to change. The calendar must already exist — calendar CREATE is not available under PIT (marketplace OAuth only).

Parameters

Example call

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

Delete a calendar. All future appointments on this calendar are cancelled. Past appointments are retained as historical records.

Parameters

Example call

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

Create a task associated with a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_task",
    "arguments": {
      "contactId": "string",
      "title": "string",
      "dueDate": "string"
    }
  }
}

Update a task — change title, body, due date, completion status.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_task",
    "arguments": {
      "contactId": "string",
      "taskId": "string"
    }
  }
}

Delete a task.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_task",
    "arguments": {
      "contactId": "string",
      "taskId": "string"
    }
  }
}

Create a note on a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_note",
    "arguments": {
      "contactId": "string",
      "body": "string"
    }
  }
}

Update the body of a note.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_note",
    "arguments": {
      "contactId": "string",
      "noteId": "string",
      "body": "string"
    }
  }
}

Delete a note.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_note",
    "arguments": {
      "contactId": "string",
      "noteId": "string"
    }
  }
}

List all custom fields configured on the sub-account (for contacts and opportunities). Useful before creating/updating contacts with custom data.

Parameters

Example call

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

Get details of a single custom field.

Parameters

Example call

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

Create a new custom field on the sub-account. After creation, the returned `id` can be referenced when setting custom-field values on contacts or opportunities. For SINGLE_OPTIONS / MULTIPLE_OPTIONS / RADIO / CHECKBOX fields, supply `options` as an array of {label, value} pairs.

Parameters

Example call

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

Update a custom field's name / options / placeholder. Pass only the fields you want to change.

Parameters

Example call

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

Delete a custom field. This removes the field definition but does not affect contact/opportunity rows that already have a value stored — those become orphaned data accessible only via raw_payload.

Parameters

Example call

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

List all sub-account custom values. Use before setting workflow merge tags or composing messages that reference {{custom_values.X}}.

Parameters

Example call

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

Get details of one custom value by id.

Parameters

Example call

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

Create a new sub-account custom value. Returns the created record including its id and the auto-generated merge-tag key ({{custom_values.<slug>}}).

Parameters

Example call

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

Update an existing custom value's name and/or value. Pass only the fields you want to change.

Parameters

Example call

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

Delete a sub-account custom value. Any merge tags referencing the deleted key will render empty in workflows/messages.

Parameters

Example call

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

List all workflows in the sub-account. Returns workflow IDs, names, and status.

Parameters

Example call

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

List all tags available on the sub-account.

Parameters

Example call

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

Create a new tag on the sub-account. Tags are referenced by NAME from contact.tags JSON arrays, so use a concise human-readable name.

Parameters

Example call

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

Rename a tag. Existing contacts tagged with the old name get the rename transitively.

Parameters

Example call

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

Delete a tag from the sub-account. Contacts that were tagged lose the tag reference; contact records themselves are not touched.

Parameters

Example call

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

List users on the sub-account. Useful for finding user IDs to assign tasks, opportunities, or appointments.

Parameters

Example call

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

Fetch a single user by ID.

Parameters

Example call

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

Fetch full details of the current sub-account (location) — name, address, timezone, business info.

Parameters

Example call

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

List all forms on the sub-account.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_forms",
    "arguments": {
      "locationId": "string",
      "limit": 0
    }
  }
}

List submissions for a specific form.

Parameters

Example call

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

List all surveys on the sub-account.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_surveys",
    "arguments": {
      "locationId": "string",
      "limit": 0
    }
  }
}

List submissions for a specific survey.

Parameters

Example call

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

COMPLETE catalog of every Topline object that exists upstream — including objects we sync (queryable via SQL), objects we've catalogued but haven't built sync for yet, objects that require OAuth/agency scopes our PIT auth can't reach, and objects we've declined to sync. Call this when topline_describe_schema doesn't show something the user is asking about — it will tell you whether the data lives on disk (queryable now), is pending (answer will lag a sync cycle), or is inaccessible (tell the user to request it instead of inventing a workaround). Contrast with topline_describe_schema, which is SCHEMA-only and hides everything not currently exposed. Returns { entries: [{ name, category, status, description, sql_table?, endpoint?, notes? }...] } with status in {exposed, syncing, catalogued, requires_oauth, inaccessible, declined}.

No parameters.

Example call

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

Overview of every table currently exposed to SQL queries in this sub-account's data warehouse. Returns table names, one-line descriptions, row counts, and a short SQLite-dialect cheat sheet. Call this FIRST when the user asks anything analytics-flavored ('how many', 'group by', 'trend', 'compare', 'duplicate'). It's cheap and tells you what's queryable. Follow up with topline_explain_tables on the ones you want to use, then topline_execute_query with the SQL.

No parameters.

Example call

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

Per-column detail for one or more tables returned by topline_describe_schema. Gives column names, SQLite types, nullability, JSON-column flags, enum values for closed-set text columns, foreign-key hints for joins, and approximate row counts. Call this before writing a SELECT so your WHERE / JOIN clauses use real column names and valid enum values. Rejects tables that aren't in the exposed set.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_explain_tables",
    "arguments": {
      "tables": [
        "string"
      ]
    }
  }
}

Run a read-only SQL query against this sub-account's SQLite warehouse. ONE SELECT or WITH...SELECT statement at a time. DDL, DML, PRAGMA, ATTACH, and admin commands are rejected by the parser before they reach the database. Results are capped at 5000 rows; larger result sets come back with truncated: true. Returns { columns, rows, elapsed_ms, truncated, effective_limit, rewritten_sql }. SQLite dialect — no DATE_TRUNC (use strftime), JSON columns need json_extract / json_each, timestamps are ISO 8601 strings that compare lexicographically.

Parameters

Example call

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

Describes the HTTP query API you can point Looker Studio, Retool, Lovable, Claude Code, n8n, or curl at for live-data dashboards. Returns URL shapes, auth format, example curl commands, and guidance for wiring up a dashboard. Use this when the user asks about building dashboards, embedding the data in another tool, or when a query is too complex for chat and they'd rather save it as a saved view.

No parameters.

Example call

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

Answer 'what uses X?' across synced CRM objects. Closed-enum dispatcher — runs hard-coded SQL per kind; no arbitrary SQL accepted. Supported kinds: tag, custom_field, custom_value, pipeline, pipeline_stage, calendar, user, contact, opportunity, form, survey. WORKFLOWS are NOT supported: the upstream platform's public API does not expose workflow internals, so we cannot know which workflows reference any given object. kind=opportunity returns ONLY direct references (the opportunity itself, its pipeline, stage, and contact) — it does NOT include downstream activity like messages or calls, since those belong to the contact and may span multiple opportunities. To get a contact's full activity, call this tool again with kind=contact using the contact_id from the opportunity's extra payload. Results are capped at 500 rows total (not per kind); truncated=true means upstream had more. For tags, accepts either the tag id or the tag name.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_find_references",
    "arguments": {
      "kind": "tag",
      "id": "string"
    }
  }
}