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

ghl-mcp-server-v2

by zackscriven

ghl_oauth_get_installed_locations

Read-onlyIdempotent

Fetch all locations where a GoHighLevel app is installed using an agency-level OAuth token, with pagination and filters for company, plan, trial status, and installation state.

Instructions

REQUIRES AN AGENCY-LEVEL (Company) TOKEN — spec security is Agency-Access-Only, no Location-Access alternative. Get Location where app is installed This API allows you fetch location where app is installed upon Endpoint: GET /oauth/installed-locations (Version header: v3; source: v3/oauth-v3.json) Requires an Agency (company-level) token. OAuth access token only — Private Integration Tokens are rejected. OAuth scopes: oauth.readonly Pagination params: pageSize — pass them to page through full result sets.

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": {
      "companyId": "<companyId>",
      "appId": "<appId>"
    },
    "name": "ghl_oauth_get_installed_locations"
  }
}

Input Schema

NameRequiredDescriptionDefault
appIdYesParameter to search by the appId
queryNoLiteral installed-location name search. Leading and trailing whitespace is ignored.
planIdNoFilters out location which are installed for specified app under the specified planId
onTrialNoFilters out locations which are installed for specified app in trial mode
pageSizeNoMax items per page (1-100). Replaces legacy `limit` parameter per AIP-158.
companyIdYesParameter to search by the companyId
pageTokenNoOpaque token returned in a previous response to fetch the next page. Replaces legacy `skip` parameter per AIP-158.
versionIdNoVersionId of the app
locationIdNolocationId
isInstalledNoFilters out location which are installed for specified app under the specified company
restrictToUserLocationsNoWhen true, restricts the list to locations the current user has access to (for restricted agency admins and account admins). When false or omitted, no user-based filter is applied for installed list; for backward compatibility, install list (isInstalled=false) is still filtered by user when this param is omitted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.1.0
    • changedInput schema / properties / query / description
      Previous value: -"Parameter to search for the installed location by name"New value: +"Literal installed-location name search. Leading and trailing whitespace is ignored."
    • addedInput schema / properties / query / maxLength
      Added value: +100
  2. First observedv2.0.0

TDQS

B3.1/5.0
Behavior4/5

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

Beyond the annotations (readOnly/idempotent/non-destructive), it discloses the auth model in unusual detail: agency-level token required, no Location-Access alternative, Private Integration Tokens rejected, oauth.readonly scope. That is exactly the kind of context an agent needs before calling. It stops short of describing sort order or response shape, keeping it from a 5.

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

Conciseness3/5

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

The tool-specific requirement is correctly front-loaded, but the agency-token requirement is stated twice (the ALL-CAPS lead line and again after the endpoint line), and the endpoint/source metadata plus the ungrammatical 'allows you fetch location where app is installed upon' waste space. Structure is serviceable but not tight.

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 an 11-parameter read endpoint with no output schema, the description covers the crucial non-obvious risks: auth level, token type, scope, and pagination. The remaining gap is directional rather than factual — it never says whether one location or many come back, which matters given the near-identical singular sibling.

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 description coverage is 100%, so the schema already explains appId, companyId, query, planId, onTrial, isInstalled, pageToken and the rest; baseline is 3. The description adds only a pagination hint, and that hint is garbled (it names pageSize rather than pageToken as the thing to pass to page through full result sets), so it adds little and is slightly imprecise.

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

Purpose3/5

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

The description says "Get Location where app is installed" and cites GET /oauth/installed-locations, which conveys a read of installed-location records. However, the verb is vague and the phrasing is singular, so it never states plainly that this is a list/collection endpoint nor distinguishes it from the sibling ghl_oauth_get_installed_location. An agent must infer 'plural' from the pagination sentence.

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

Usage Guidelines2/5

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

It states the hard prerequisite (agency-level token, OAuth only, oauth.readonly scope) but gives no guidance on when to choose this over ghl_oauth_get_installed_location or the other oauth tools. There is no when-to-use or when-not-to-use statement at all.

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