Name: HeyNeighbor
Author: HeyNeighbor

What is the HeyNeighbor MCP server?

HeyNeighbor connects AI assistants to community documents and forms through the Model Context Protocol (MCP). Residents can find rules, read source material, and prepare supported form submissions with their own account permissions.

This public reference describes the connection. Community records require authorization and are never published here.

Why use HeyNeighbor with your AI?

HeyNeighbor delivers the best community document search and retrieval technology on the market, with the easiest AI and apps to use in community management. Communities see exceptional adoption and usage because residents can find information and get things done with less effort.

Get community information and take action in one conversation. HeyNeighbor brings document discovery, source links, form templates, and confirmed submissions to ChatGPT, Claude, and Grok.

Residents spend less effort finding the right information. Community teams make self-service easier to use, while community permissions stay in control.

What is the HeyNeighbor MCP endpoint?

Use the HTTPS endpoint below with Streamable HTTP transport and OAuth authorization.

https://www.heyneighbor.ai/api/connectors/mcp

The endpoint is an MCP server, not a page for entering account credentials. Use your AI platform to start the connection.

How do I connect HeyNeighbor to my AI?

Add the HeyNeighbor MCP endpoint in your platform’s remote MCP connection configuration, then complete HeyNeighbor sign-in and consent.

Select your AI platform below.
Configure a remote MCP server using https://www.heyneighbor.ai/api/connectors/mcp, Streamable HTTP, and OAuth.
Follow the authorization request to HeyNeighbor. Sign in and select the communities and permissions you want to allow.
Return to your AI and ask it to list your connected communities. Choose a community before requesting records.

The exact connection controls and account requirements depend on your platform. If you cannot configure a remote MCP connection, consult that platform’s connection documentation or account administrator.

Connect ChatGPT

In ChatGPT, configure a remote MCP connection with the endpoint above and OAuth authorization. Complete HeyNeighbor consent, then ask: “List my connected HeyNeighbor communities.”

Connect Claude

In Claude, configure a remote MCP connection with the endpoint above and OAuth authorization. Complete HeyNeighbor consent, then ask: “List my connected HeyNeighbor communities.”

Connect Grok

In Grok, configure a remote MCP connection with the endpoint above and OAuth authorization. Complete HeyNeighbor consent, then ask: “List my connected HeyNeighbor communities.”

Which AI platforms work with HeyNeighbor?

HeyNeighbor supports ChatGPT, Claude, and Grok. Each connection uses the same community permissions, MCP tools, and plan rules.

ChatGPT setup — Bring your community documents and supported forms into ChatGPT.
Claude setup — Work with your community documents and supported forms in Claude.
Grok setup — Find community information and work with supported forms in Grok.

Platform accounts and remote MCP availability are controlled by each provider.

How does authentication work?

HeyNeighbor uses OAuth authorization code flow with PKCE, dynamic client registration, and bearer access tokens. You choose the communities and scopes during consent.

Document access: docs:read
Read form templates: forms:read
Submit confirmed forms: forms:submit
Refresh authorization: offline_access

Discover the authorization server and its supported endpoints from the live metadata:

Do not send passwords to tools. Follow the OAuth sign-in and consent flow.

Which MCP tools are available?

HeyNeighbor exposes 7 tools. The tools advertised for an authorized connection depend on its granted scopes.

Tool inputs and required OAuth scopes
Tool	Scope	Inputs and limits
`list_communities`	`docs:read` (any granted tool scope)	offset ≥ 0; default 0; limit 1–100 (default 50).
`search`	`docs:read`	query: 1–500 characters; limit 1–20 (default 10); optional communityId.
`fetch`	`docs:read`	id: document ID; optional communityId.
`query_document`	`docs:read`	documentId; optional query: 1–500 characters; offset ≥ 0; default 0; limit 1–20,000 characters (default 8,000); optional communityId.
`list_forms`	`forms:read`	offset ≥ 0; default 0; limit 1–50 (default 20); optional communityId.
`prepare_form_submission`	`forms:submit`	templateId; title and description metadata; formData containing known answers; optional communityId. Missing answers are completed on the draft page. Does not submit.
`submit_form`	`forms:submit`	templateId; title: 1–500 characters; description: 1–10,000 characters; formData; confirmed: true; idempotencyKey: 8–128 characters; optional communityId, attachments, propertySubmissionConfirmed, propertySelections (up to 100).

Document, template, and community IDs are 24-character hexadecimal IDs returned by HeyNeighbor. Use returned IDs; do not invent them. Supply communityId when more than one community is connected.

list_communities: Published tool contract

List communities enabled for this connection. Present community names to the user as a numbered list so they can choose by number or name. Resolve a numeric choice to the corresponding returned community ID; never use the list number as communityId. With several communities, ask the user which one they mean unless they named it. New memberships require new consent.

{
  "name": "list_communities",
  "title": "list communities",
  "description": "List communities enabled for this connection. Present community names to the user as a numbered list so they can choose by number or name. Resolve a numeric choice to the corresponding returned community ID; never use the list number as communityId. With several communities, ask the user which one they mean unless they named it. New memberships require new consent.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "offset": {
        "default": 0,
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "limit": {
        "default": 50,
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      }
    },
    "required": [
      "offset",
      "limit"
    ],
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "_meta": {
    "securitySchemes": [
      {
        "type": "oauth2",
        "scopes": [
          "docs:read"
        ]
      }
    ]
  }
}

search: Published tool contract

Find document names and links in an enabled community. Paid and eligible Trial communities also support content search. Free results contain no document text. Use list_communities if the community is unclear.

{
  "name": "search",
  "title": "search",
  "description": "Find document names and links in an enabled community. Paid and eligible Trial communities also support content search. Free results contain no document text. Use list_communities if the community is unclear.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "minLength": 1,
        "maxLength": 500
      },
      "limit": {
        "default": 10,
        "type": "integer",
        "minimum": 1,
        "maximum": 20
      },
      "communityId": {
        "type": "string",
        "pattern": "^[a-f0-9]{24}$"
      }
    },
    "required": [
      "query",
      "limit"
    ],
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "_meta": {
    "securitySchemes": [
      {
        "type": "oauth2",
        "scopes": [
          "docs:read"
        ]
      }
    ]
  }
}

fetch: Published tool contract

Fetch document text by id in a Paid or eligible Trial community. Free communities can look up document names and links through search.

{
  "name": "fetch",
  "title": "fetch",
  "description": "Fetch document text by id in a Paid or eligible Trial community. Free communities can look up document names and links through search.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "pattern": "^[a-f0-9]{24}$"
      },
      "communityId": {
        "type": "string",
        "pattern": "^[a-f0-9]{24}$"
      }
    },
    "required": [
      "id"
    ],
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "_meta": {
    "securitySchemes": [
      {
        "type": "oauth2",
        "scopes": [
          "docs:read"
        ]
      }
    ]
  }
}

query_document: Published tool contract

Find document text excerpts in a Paid or eligible Trial community. AI document questions are unavailable on Free.

{
  "name": "query_document",
  "title": "query document",
  "description": "Find document text excerpts in a Paid or eligible Trial community. AI document questions are unavailable on Free.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "documentId": {
        "type": "string",
        "pattern": "^[a-f\\d]{24}$"
      },
      "query": {
        "type": "string",
        "minLength": 1,
        "maxLength": 500
      },
      "offset": {
        "default": 0,
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "limit": {
        "default": 8000,
        "type": "integer",
        "minimum": 1,
        "maximum": 20000
      },
      "communityId": {
        "type": "string",
        "pattern": "^[a-f0-9]{24}$"
      }
    },
    "required": [
      "documentId",
      "offset",
      "limit"
    ],
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "_meta": {
    "securitySchemes": [
      {
        "type": "oauth2",
        "scopes": [
          "docs:read"
        ]
      }
    ]
  }
}

list_forms: Published tool contract

List and read form templates in the specified community. Present form names to the user as a numbered list so they can choose by number or name. Resolve a numeric choice to the corresponding returned template ID; never use the list number as templateId. Free communities can read forms; submitting requires a paid plan. For submissionMode draft, ask only for the main request details and then call prepare_form_submission promptly. Leave missing dates, property selection, detailed fields, acknowledgements and attachments for the draft page; do not require a full chat interview. For submissionMode chat, simple forms can be completed and confirmed in chat. Do not search governing documents unless the user asks for that help.

{
  "name": "list_forms",
  "title": "list forms",
  "description": "List and read form templates in the specified community. Present form names to the user as a numbered list so they can choose by number or name. Resolve a numeric choice to the corresponding returned template ID; never use the list number as templateId. Free communities can read forms; submitting requires a paid plan. For submissionMode draft, ask only for the main request details and then call prepare_form_submission promptly. Leave missing dates, property selection, detailed fields, acknowledgements and attachments for the draft page; do not require a full chat interview. For submissionMode chat, simple forms can be completed and confirmed in chat. Do not search governing documents unless the user asks for that help.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "offset": {
        "default": 0,
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "limit": {
        "default": 20,
        "type": "integer",
        "minimum": 1,
        "maximum": 50
      },
      "communityId": {
        "type": "string",
        "pattern": "^[a-f0-9]{24}$"
      }
    },
    "required": [
      "offset",
      "limit"
    ],
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "_meta": {
    "securitySchemes": [
      {
        "type": "oauth2",
        "scopes": [
          "forms:read"
        ]
      }
    ]
  }
}

prepare_form_submission: Published tool contract

Start a partial draft from the main request details and return its prefilled HeyNeighbor page link. Use this early for complex forms (submissionMode draft), after the user describes the main project or request; do not collect every required field in chat. Preserve supplied values using returned field IDs and omit unknown answers. Use the template name and a summary of the user request for title and description metadata; do not ask for these as extra fields. Do not invent dates, property choices or acknowledgement answers. The user completes missing fields, adds files, reviews acknowledgements and explicitly submits on the page. This tool never submits the form. Also use it when the host cannot provide requested files.

{
  "name": "prepare_form_submission",
  "title": "prepare form submission",
  "description": "Start a partial draft from the main request details and return its prefilled HeyNeighbor page link. Use this early for complex forms (submissionMode draft), after the user describes the main project or request; do not collect every required field in chat. Preserve supplied values using returned field IDs and omit unknown answers. Use the template name and a summary of the user request for title and description metadata; do not ask for these as extra fields. Do not invent dates, property choices or acknowledgement answers. The user completes missing fields, adds files, reviews acknowledgements and explicitly submits on the page. This tool never submits the form. Also use it when the host cannot provide requested files.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "templateId": {
        "type": "string",
        "pattern": "^[a-f\\d]{24}$"
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 500
      },
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10000
      },
      "formData": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "propertySubmissionConfirmed": {
        "type": "boolean"
      },
      "propertySelections": {
        "maxItems": 100,
        "type": "array",
        "items": {}
      },
      "communityId": {
        "type": "string",
        "pattern": "^[a-f0-9]{24}$"
      }
    },
    "required": [
      "templateId",
      "title",
      "description",
      "formData"
    ],
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": false,
    "openWorldHint": false
  },
  "_meta": {
    "securitySchemes": [
      {
        "type": "oauth2",
        "scopes": [
          "forms:submit"
        ]
      }
    ]
  }
}

submit_form: Published tool contract

Submit only after the user reviews all values, attachment names and the destination community, and explicitly confirms. Attach host-provided files using attachments. If this host cannot provide requested files, use prepare_form_submission and give the user the HeyNeighbor page link. Never silently omit requested files. Reuse idempotencyKey for retries.

{
  "name": "submit_form",
  "title": "submit form",
  "description": "Submit only after the user reviews all values, attachment names and the destination community, and explicitly confirms. Attach host-provided files using attachments. If this host cannot provide requested files, use prepare_form_submission and give the user the HeyNeighbor page link. Never silently omit requested files. Reuse idempotencyKey for retries.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "templateId": {
        "type": "string",
        "pattern": "^[a-f\\d]{24}$"
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 500
      },
      "description": {
        "type": "string",
        "minLength": 1,
        "maxLength": 10000
      },
      "formData": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "attachments": {
        "maxItems": 10,
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "download_url": {
              "type": "string",
              "maxLength": 8192,
              "format": "uri"
            },
            "file_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            },
            "mime_type": {
              "type": "string",
              "maxLength": 200
            },
            "file_name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 255
            }
          },
          "required": [
            "download_url",
            "file_id"
          ],
          "additionalProperties": false
        }
      },
      "confirmed": {
        "type": "boolean",
        "const": true
      },
      "propertySubmissionConfirmed": {
        "type": "boolean"
      },
      "propertySelections": {
        "maxItems": 100,
        "type": "array",
        "items": {}
      },
      "communityId": {
        "type": "string",
        "pattern": "^[a-f0-9]{24}$"
      },
      "idempotencyKey": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128
      }
    },
    "required": [
      "templateId",
      "title",
      "description",
      "formData",
      "confirmed",
      "idempotencyKey"
    ],
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "_meta": {
    "securitySchemes": [
      {
        "type": "oauth2",
        "scopes": [
          "forms:submit"
        ]
      }
    ],
    "openai/fileParams": [
      "attachments"
    ]
  }
}

What can a connected AI access?

A connected AI can use only the consented communities and scopes that your current account can access. Consent does not expand your community role.

HeyNeighbor checks current consent and active, approved community membership or eligible organization assignment. Employee status does not bypass these checks. Document access also follows document, category, household, and subcommunity restrictions.

Use list_communities to choose the destination. There is no default community when several are connected. New memberships need new consent. A revoked connection or removed membership cannot continue to access records.

Which features are available on Free, Paid, and Trial plans?

Free communities can find document names and links and read available form templates. Paid and eligible Trial communities can also retrieve document text, search content, and submit permitted forms.

Capability	Free	Paid / eligible Trial
Document names and links	Yes	Yes
Document text, fetch, and questions	No	Yes
Read form templates	Yes	Yes
Submit forms	No	Yes

Community eligibility, enabled features, permissions, and template rules still apply. See HeyNeighbor plans.

How do form submissions and attachments work?

The AI must show all values, attachment names, and the destination community for review and receive your explicit confirmation before it submits a form.

Call list_forms for the template and field IDs. Submit with confirmed: true and an idempotencyKey of 8–128 characters. Retry the same payload with the same key. If the result is uncertain, do not create a fresh key: that can create a duplicate submission.

Users can upload documents, images, and videos for supported forms in ChatGPT and Claude. Supply user-provided files through attachments. Each file requires download_url and file_id; mime_type and file_name are optional. The host platform’s file attachment mechanism can differ. Never silently omit a requested file.

Up to 10 files and 100 MB total.
Up to 5 MB per image, 10 MB per document, and 50 MB per video. Supported video formats are MP4, MOV, and WebM.
formData: up to 200 keys and 100,000 serialized characters.

Payments and signatures are not supported through these tools. Complete forms that require payment or signature in HeyNeighbor. Successful submissions return a receipt with the form ID, title, status, and submitted date.

How does search work, and can I cite the results?

Search uses case-insensitive literal text matching. Free plans search document names. Paid and eligible Trial plans also search stored document text.

search returns document IDs, titles, and source URLs, with text excerpts when allowed. fetch retrieves an initial text segment. query_document returns a matching excerpt or text from the requested offset, plus pagination information. A query without a match can still return text; inspect queryMatched.

Use the returned source URL to cite a document. Open the source in HeyNeighbor to verify context. If results are empty, check the selected community, your permissions, and the exact words in the document.