MCP connector

Endpoint

POST https://app.greenfinch.ai/api/v1/mcp

• Version negotiation. initialize echoes the protocolVersion you ask for when it is supported; otherwise it answers with the newest supported version that is not newer than yours. Clients on the 2026-07-28 revision can call server/discover instead.
• Event stream. A GET to the same URL opens a server-sent-events stream. Greenfinch never pushes messages — every tool answers in its POST response — so the stream only carries keep-alive comments and closes after about 55 minutes. Clients that require it reconnect automatically; scripts can ignore it.
• Methods. initialize, server/discover, ping, tools/list, tools/call, prompts/list and prompts/get. Notifications such as notifications/initialized are accepted with 202 and no body.
• Caching. tools/list and prompts/list include ttlMs: 3600000; the tool list only changes when Greenfinch releases.
• Prompts. prompts/list returns ready-made multi-step plans (for example, building a prospect list for a county) that assistants can offer as shortcuts.

Connect an AI assistant

Claude, ChatGPT and other assistants with connectors

Assistants that support remote MCP connectors add Greenfinch by URL. Enter https://app.greenfinch.ai/api/v1/mcp as the connector URL. Where the assistant supports MCP sign-in, each member connects with their own Greenfinch account and the assistant acts as that member — see per-user connections. Menu names differ between assistants and change often; look for “connectors” or “custom MCP server” in its settings.

Clients configured with a file

Developer tools and agent frameworks that let you set request headers can use an organization key directly. A typical server entry (field names vary slightly by client):

{
  "mcpServers": {
    "greenfinch": {
      "type": "http",
      "url": "https://app.greenfinch.ai/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${GREENFINCH_API_KEY}"
      }
    }
  }
}

Call it from code

No MCP library is required. Send a JSON-RPC request with your key; the answer is in the response body.

curl -X POST "https://app.greenfinch.ai/api/v1/mcp" \
  -H "Authorization: Bearer $GREENFINCH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "greenfinch_browse_contacts",
    "arguments": {
      "employerText": "Lakeside Property Services",
      "titleText": "facilities",
      "limit": 10
    }
  }
}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"contacts\": [ … ],\n  \"total_matching\": 1\n}"
      }
    ],
    "structuredContent": {
      "contacts": [
        {
          "contact_id": "3f2a9c1e-0000-4000-8000-000000000041",
          "title": "Director of Facilities",
          "role_type": "facilities_operations",
          "seniority": "director",
          "employer_name": "Lakeside Property Services",
          "property_count_in_territory": 6,
          "revealed": false,
          "email_validated": true,
          "has_phone": true
        }
      ],
      "total_matching": 1
    }
  }
}

• structuredContent is the result the tool returns, as JSON — parse this.
• content[0].text carries the same data as text (sometimes after a one-line summary), for assistants that only read text.
• Unrevealed contacts are listed without personal details. Reveal one with greenfinch_reveal_contact.

Official MCP SDKs work too: point a Streamable HTTP client transport at the endpoint and add the Authorization header.

Errors and refusals

A call can fail at three levels, and each looks different:

A refusal is a business answer the caller can act on, so it arrives as a successful JSON-RPC response. Its structuredContent always has a machine code and a message, plus any detail; the text content starts with CODE: message so text-only clients see the code too.

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "INSUFFICIENT_CREDITS: Insufficient credits\n\n{ \"code\": \"INSUFFICIENT_CREDITS\", … }"
      }
    ],
    "isError": true,
    "structuredContent": {
      "code": "INSUFFICIENT_CREDITS",
      "message": "Insufficient credits",
      "required": 10,
      "available": 4
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 8,
  "error": {
    "code": -32602,
    "message": "Unknown tool: \"greenfinch_search_property\". Did you mean: greenfinch_search_properties?"
  }
}

Refusals that apply to every tool

On a per-user connection, these checks run before any tool, mirroring what the member could do in the app:

Organization keys skip these, but tools that must be attributed to a person (for example greenfinch_add_note) refuse keys with ACTING_USER_REQUIRED. Every other code is listed on each tool in the tool reference and explained on Limits and errors.

Tool markers

The tool reference labels every tool so you can tell, before calling it, what it will do.tools/list carries the first of these as the standard readOnlyHint annotation.