Tools Reference

Every tool call is a standard MCP tools/call request and returns a standard CallToolResult: a content array (a text block your model reads) plus, on success, structuredContent (the same payload as parsed JSON, for clients that support it). A failed call sets isError: true and puts a message the model can act on in the text block — never a raw stack trace or protocol error.

search_apis

Find which operations can serve an intent. Call this whenever you don’t already know the exact operationId — it searches every available operation and returns candidates with their id and a one-line summary.

string

required

What you’re trying to do, in plain words — e.g. “find buyer leads created last week” or “reassign a lead to another agent”.

integer

default:"8"

Maximum results to return. Maximum 25.

Request

curl https://mcp.lofty.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {"name": "search_apis", "arguments": {"query": "get a lead by id"}}
  }'

Response

{
  "operations": [
    {"operationId": "lead_get", "method": "GET", "path": "/v1.0/leads/{leadId}", "summary": "Get Lead"},
    {"operationId": "leadTask_getTaskById", "method": "GET", "path": "/v1.0/tasks/{taskId}", "summary": "Get Task (V1)"}
  ],
  "next": "Call describe_api with an operationId to see its parameters."
}

Ranking is a weighted keyword match over each operation’s real documentation — not semantic search. The right operation reliably appears within the top few results, but isn’t always first. Read the summaries of results 2–5 before concluding nothing fits or retrying with different wording.

describe_api

Return the full parameter schema for one operation: every argument invoke_api accepts, with types, allowed values, and documentation. Call this after search_apis and before invoke_api.

string

required

An operationId returned by search_apis, e.g. lead_update.

Request

curl https://mcp.lofty.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {"name": "describe_api", "arguments": {"operationId": "lead_get"}}
  }'

Response

{
  "operationId": "lead_get",
  "method": "GET",
  "path": "/v1.0/leads/{leadId}",
  "summary": "Get Lead",
  "description": "Returns a single lead by its ID...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "leadId": {"type": "integer", "description": "ID of the lead to retrieve."},
      "withTrash": {"type": "boolean", "description": "When true, include trashed leads in the lookup."}
    },
    "required": ["leadId"]
  },
  "readOnly": true
}

If the operation modifies or deletes data, the response includes a "warning" field saying so — confirm with the user before calling it.

invoke_api

Execute one operation. Path and query parameters go at the top level of arguments; a request body goes under a nested body key.

string

required

The operation to call, as returned by search_apis.

object

Arguments for the operation, exactly as described by describe_api.

Request (path parameter)

curl https://mcp.lofty.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "invoke_api", "arguments": {"operationId": "lead_get", "arguments": {"leadId": 100001}}}
  }'

Request (with a body)

curl https://mcp.lofty.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "jsonrpc": "2.0", "id": 4, "method": "tools/call",
    "params": {
      "name": "invoke_api",
      "arguments": {
        "operationId": "lead_update",
        "arguments": {"leadId": 100001, "body": {"firstName": "Ada"}}
      }
    }
  }'

A successful call’s text content is the underlying API’s own JSON response body, unchanged. A failed call — invalid arguments, an operation the caller isn’t authorized for, a record that doesn’t exist — is returned as a tool error carrying the real HTTP status and body:

Error example

{
  "content": [{"type": "text", "text": "The Lofty API returned HTTP 404: {\"message\":\"...Lead not exist\"}"}],
  "isError": true
}

invoke_api runs as the authenticated caller with their existing permissions — a call the user couldn’t make through the CRM directly will be refused here too. Operations describe_api marks as modifying or deleting data should be confirmed with the user before calling.

A very large response is truncated with a leading NOTE: ... line explaining what was cut and how to get the rest — read that line before treating a trimmed list as the complete answer.

list_custom_fields

Return the custom lead field definitions configured on the caller’s team, with the ids to use when reading or writing their values. Custom fields are defined per team, so they can’t appear in any operation’s static schema — call this before setting or filtering on a field name you don’t recognize. This tool takes no arguments.

Request

curl https://mcp.lofty.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "jsonrpc": "2.0", "id": 5, "method": "tools/call",
    "params": {"name": "list_custom_fields", "arguments": {}}
  }'

Response

[
  {"attributeName": "custom text", "attributeType": "text", "value": "", "params": "{\"attributeName\":\"custom text\",\"attributeType\":\"text\"}"},
  {"attributeName": "custom signSelect", "attributeType": "single_select", "value": "", "params": "{\"attributeName\":\"custom signSelect\",\"attributeType\":\"single_select\",\"option\":[\"A1\",\"B1\",\"C1\"]}"}
]

Get Started

Authentication

Core Concepts

Guides

Lofty CLI

MCP Server

search_apis

describe_api

invoke_api

list_custom_fields

​search_apis

​describe_api

​invoke_api

​list_custom_fields

search_apis

describe_api

invoke_api

list_custom_fields