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

ghl-mcp-server-v2

by zackscriven

ghl_oauth_exchange_location_token

Exchange an agency-level OAuth token for a location-scoped access token by submitting companyId and locationId, enabling location-specific API access.

Instructions

REQUIRES AN AGENCY-LEVEL (Company) TOKEN — spec security is Agency-Access-Only. Body is application/x-www-form-urlencoded per spec (companyId, locationId as form fields), not JSON. This is the standard way to mint a location-scoped token from an agency token. Get Location Access Token from Agency Token This API allows you to generate locationAccessToken from AgencyAccessToken Endpoint: POST /oauth/location-token (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.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": {
      "body": "<body>"
    },
    "name": "ghl_oauth_exchange_location_token"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.1.0
    • addedInput schema / properties / body / title
      Added value: +"GetLocationAccessCodeBodyDto"
  2. First observedv2.0.0

TDQS

A4.2/5.0
Behavior5/5

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

Beyond the annotations (non-readOnly, openWorld, non-idempotent), the description discloses the two things that actually trip up callers: the body must be application/x-www-form-urlencoded rather than JSON, and Private Integration Tokens are rejected in favor of OAuth tokens. It also names the required scope (oauth.write) and version header.

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

Conciseness4/5

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

The most critical constraint (agency-level token, form encoding) is front-loaded in the first two sentences. There is mild redundancy afterwards — "Get Location Access Token from Agency Token" restates the title and the following sentence restates it again — but nothing is misleading.

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?

With no output schema, the description should ideally say what the response contains (locationAccessToken, expiry), and it only implies this. Everything needed to construct a correct call — auth level, encoding, endpoint, scope — is present, so the gap is minor for an auth-exchange tool.

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

Parameters4/5

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

Schema coverage is 100%, so the nested companyId/locationId properties are already documented, which sets a baseline of 3. The description earns the extra point by specifying that these are submitted as form fields under an urlencoded body rather than as a JSON payload — a meaning the schema alone does not convey.

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?

States a specific verb and resource: mint a location-scoped access token from an agency-level token, with the endpoint (POST /oauth/location-token) made explicit. It does not, however, distinguish itself from the closely named sibling ghl_oauth_get_location_access_token, so an agent cannot tell from the description alone which of the two to pick.

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

Usage Guidelines4/5

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

"This is the standard way to mint a location-scoped token from an agency token" plus the explicit requirement of an Agency/company-level token and the rejection of Private Integration Tokens gives clear use conditions. It stops short of naming an alternative tool or stating when not to use this one.

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