Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_form_upload_custom_files

Uploads files to a contact's GoHighLevel form custom fields; supports multiple attachments, allowed file types, and a 50 MB size limit.

Instructions

EXCEPTION — no callable body schema: the official spec documents this endpoint's multipart/form-data requestBody as a bare empty object (no fields listed), so this tool's generated input schema has NO body property at all; there is currently no way to attach file bytes through this tool. Per the spec's prose, fields must be a buffer keyed <custom_field_id>_<file_id> (custom field ID + a random file id), max 50MB, one of PDF/DOCX/DOC/JPG/JPEG/PNG/GIF/CSV/XLSX/XLS/MP4/MPEG/ZIP/RAR/TXT/SVG. Fixing this requires a registry.ts change (a hand-written schema override capability that doesn't exist yet), which is out of scope for this docs-only override pass — flagged as an exception in the audit. Upload files to custom fields Post the necessary fields for the API to upload files. The files need to be a buffer with the key "< custom_field_id >_< file_id >". Here custom field id is the ID of your custom field and file id is a randomly generated id (or uuid) There is support for multiple file uploads as well. Have multiple fields in the format mentioned.File size is limited to 50 MB. The allowed file types are: PDFDOCXDOCJPGJPEGPNGGIFCSVXLSXXLSMP4MPEGZIPRARTXTSVG The API will return the updated contact object. Endpoint: POST /forms/upload-custom-files (Version header: v3; source: v3/forms-v3.json) Requires a Sub-Account (location) token. OAuth scopes: forms.write

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "contactId": "<contactId>",
      "locationId": "<locationId>",
      "body": "<body>"
    },
    "name": "ghl_form_upload_custom_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body. The official spec provides no field-level schema for this body; pass fields as documented. For multipart uploads, file values may be given as { filePath, filename?, mimeType? } objects.
contactIdYesContact ID to upload the file to.
locationIdYesLocation ID of the contact.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0

TDQS

A3.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (which already mark this as non-read-only, non-idempotent, open-world), the description discloses the Sub-Account/location token requirement, the forms.write OAuth scope, the 50MB ceiling, the allowed MIME types, the `<custom_field_id>_<file_id>` key convention, and that the updated contact object is returned. That is a substantive behavioral payload well past the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical exception caveat is front-loaded correctly, but it is followed by two near-duplicate restatements of the same upload rules and raw `<br/>`/`<ul><li>` spec markup repeated verbatim. The file-type list appears twice and the prose is not trimmed, so the description is markedly longer than its actual information content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that is effectively non-functional, the description is unusually complete: it explains why the body schema is empty, what the correct payload would look like, the auth/token and scope requirements, size and type limits, and the return value. The only real omission is a pointer to the sibling tool that could accomplish the upload.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description does add real value by specifying the multipart key format and file constraints that neither the schema nor the field descriptions convey. However, its claim that the schema has "NO `body` property at all" is contradicted by the actual schema, which does expose an additionalProperties `body` object, creating confusion about what can be passed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Upload files to custom fields", POST /forms/upload-custom-files) targeting a contact's custom fields, so the operation is unambiguous. It does not, however, distinguish itself from the close sibling ghl_location_upload_file_custom_fields, leaving the agent to guess which upload path applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The leading EXCEPTION block functions as an implicit "do not use" signal by declaring there is currently no way to attach file bytes through this tool, which is genuinely useful guidance. But no alternative tool is named for achieving the same outcome, so the agent is told the tool is broken without being routed elsewhere.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools