Beacon CRM MCP by usefulapi

List the record types of this Beacon account (people, organisations, payments, custom types, ...) with their fields (keys, types, options). Call this first: the keys are what the other tools take as `entity` and as field names. GET /entity_types.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the users of the Beacon account (id, role, name, email). Use the inner user.id for 'link to a user' fields. GET /users.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "per_page": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List records of one type (for example person, organization, payment), one page at a time. Use beaconcrm_filter_records to search by field values. GET /entities/{entity}.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "per_page": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "sort_by": {
      "description": "Field key to sort by, e.g. created_at.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_.]{1,100}$"
    },
    "sort_direction": {
      "description": "Sort direction (default: Beacon's default order).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "populate": {
      "description": "Include data from linked records (point-to-another-record fields). Beacon's default applies when omitted.",
      "type": "boolean"
    },
    "archived": {
      "description": "true = list deleted (archived) records instead of active ones.",
      "type": "boolean"
    }
  },
  "required": [
    "entity"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One record by type and id, with all its fields. GET /entity/{entity}/{id}.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Record id."
    },
    "populate": {
      "description": "Include data from linked records (point-to-another-record fields). Beacon's default applies when omitted.",
      "type": "boolean"
    }
  },
  "required": [
    "entity",
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search records of one type with Beacon filter conditions (read-only; it uses POST because the filter is a body). Each condition is {"field", "operator", "value"}. Operators by field type: text == != starts_with ends_with contains not_contains null not_null; select (value is an array) contains not_contains in not_in null not_null; number == != > < null not_null; date date_on date_after date_before date_between (value e.g. "2026-01-01", "last_month", or ["2026-01-01","2026-06-01"]); checkbox == true; point-to-record (value is an array of ids) contains not_contains. Location parts: address.city etc.; emails: emails.email. Conditions can nest as {"filter_conditions": [...], "filter_strictness": "all"|"any"}. Example: [{"field":"emails.email","operator":"==","value":"[email protected]"}]. POST /entities/{entity}/filter.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "filter_conditions": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "description": "Filter conditions (see the description). An empty list matches every record."
    },
    "filter_strictness": {
      "description": "\"all\" = AND (default), \"any\" = OR.",
      "type": "string",
      "enum": [
        "all",
        "any"
      ]
    },
    "page": {
      "description": "Page number, from 1 (default 1). Pass the previous reply's next_page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100000
    },
    "per_page": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "sort_by": {
      "description": "Field key to sort by, e.g. created_at.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_.]{1,100}$"
    },
    "sort_direction": {
      "description": "Sort direction (default: Beacon's default order).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "populate": {
      "description": "Include data from linked records (point-to-another-record fields). Beacon's default applies when omitted.",
      "type": "boolean"
    },
    "archived": {
      "description": "true = list deleted (archived) records instead of active ones.",
      "type": "boolean"
    }
  },
  "required": [
    "entity",
    "filter_conditions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create ONE new record of the given type in the live Beacon database. Not idempotent: calling it twice creates two records (use beaconcrm_upsert_record to avoid duplicates). Beacon workflows may run as a result. Invalid field values are rejected with the rule that failed. POST /entity/{entity}.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {\"type\": [\"Donation\"], \"customer\": [1725]}); emails are [{\"email\", \"is_primary\"}]; currency is {\"value\", \"currency\"}; dates are ISO strings."
    }
  },
  "required": [
    "entity",
    "fields"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: change fields of ONE existing record. Only the fields you pass are changed; a select or reference field passed as an empty array [] is CLEARED, removing its existing values. The previous values are not kept by this tool. Beacon workflows may run as a result. PATCH /entity/{entity}/{id}.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Record id."
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {\"type\": [\"Donation\"], \"customer\": [1725]}); emails are [{\"email\", \"is_primary\"}]; currency is {\"value\", \"currency\"}; dates are ISO strings."
    }
  },
  "required": [
    "entity",
    "id",
    "fields"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a record, or update the existing one whose key field matches. `primary_field_key` names the field used to find the match (for example "emails" for a person, or "external_id"); `fields` must contain a value for it. If a record matches it is UPDATED with the given fields (an empty array leaves an existing value untouched on upsert); otherwise a new record is created. Beacon workflows may run as a result. PUT /entity/{entity}/upsert.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "primary_field_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_.]{1,100}$",
      "description": "Field key used to match an existing record, e.g. emails or external_id."
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Field values keyed by field key, in Beacon's field formats (see beaconcrm_list_record_types for keys). Select and point-to-record fields are ARRAYS (e.g. {\"type\": [\"Donation\"], \"customer\": [1725]}); emails are [{\"email\", \"is_primary\"}]; currency is {\"value\", \"currency\"}; dates are ISO strings."
    }
  },
  "required": [
    "entity",
    "primary_field_key",
    "fields"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, DESTRUCTIVE: delete ONE record. Beacon keeps deleted records as 'archived' (listable with archived=true), but this server has no restore tool, so treat the deletion as irreversible. Related data that depends on the record may be affected. It is sent once and never retried. DELETE /entity/{entity}/{id}.

{
  "type": "object",
  "properties": {
    "entity": {
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$",
      "description": "Record type key, e.g. person, organization, payment or a custom type such as c_application. See beaconcrm_list_record_types."
    },
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Id of the record to delete."
    }
  },
  "required": [
    "entity",
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: start an export job from an existing export template (created in Beacon). Returns the new export's id with status in_progress; then poll beaconcrm_list_exports with that id until progress is 100 and it carries a download url. Each call starts another job. POST /entity_export/trigger.

{
  "type": "object",
  "properties": {
    "entity_export_template_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Id of the export template (shown in the Beacon URL when you view the template)."
    }
  },
  "required": [
    "entity_export_template_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List recent export jobs with status, progress (100 = complete) and, when complete, a signed download url. Pass entity_export_id to check one job started by beaconcrm_trigger_export. GET /entity_exports.

{
  "type": "object",
  "properties": {
    "entity_export_id": {
      "description": "Only this export (the id returned by beaconcrm_trigger_export).",
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{1,64}$"
        }
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}