Skip to content
SMBcrmSMBcrm Developers

MCP Server

SMBcrm runs a Model Context Protocol (MCP) server, so an AI assistant or agent (Claude, ChatGPT, Cursor, a custom agent, or an automation tool like n8n) can read and act on your account through one connection. There are two ways to connect:

Sign in (OAuth) Private Integration Token
Use it for Claude.ai, ChatGPT, Muse, and Claude Code or Codex if you’d rather sign in than manage a token Agents and automations you run yourself: Claude Code, Cursor, n8n, your own agent
URL One per AI client (see below) https://services.smbcrm.com/mcp/
Auth Sign in and approve access in the browser Authorization: Bearer <pit-token>
Tools Four tools that search and run hundreds of operations A fixed set of tools, one per operation

Either way, the connection acts on one SMBcrm account/location, and the permissions you grant decide what the assistant can do.

Sign in with OAuth

Section titled “Sign in with OAuth”

Each AI client has its own URL:

Client URL
Claude (Claude.ai, Claude Code, Claude Cowork) https://services.leadconnectorhq.com/mcp/anthropic/v2
ChatGPT, Codex and other OpenAI clients https://services.leadconnectorhq.com/mcp/openai/v2/
Muse https://services.leadconnectorhq.com/mcp/muse/v2/

Use the URL exactly as shown, including the trailing slash on the OpenAI and Muse URLs. A client connected to another client’s URL is refused.

When you connect, the client opens a browser window to sign in. The sign-in and approval screens are hosted on services.leadconnectorhq.com and show the LeadConnector name. That’s expected: sign in with your SMBcrm email and password, choose your account/location, and approve.

  1. Open Settings → Connectors → Add custom connector.
  2. Enter https://services.leadconnectorhq.com/mcp/anthropic/v2 as the server URL.
  3. Click Connect, sign in, choose your account/location and approve.
  4. Start a new chat. The tools are available there.

Claude Cowork works the same way: add a custom connector with the same URL.

How the tools work

Section titled “How the tools work”

A signed-in connection gives the assistant four tools in place of one tool per operation:

Tool What it does
list_locations Returns the account/location the connection is bound to.
search_operations Finds operations by intent, including record searches.
describe_operation Returns an operation’s inputs, an example payload, the scopes it needs and its safety information.
execute_operation Runs an operation after checking scopes, permissions and safety rules.

To act on a request, the assistant searches for operations, describes the ones it picks, then executes them. Asked to find a contact by email and add a tag, it calls search_operations, then describe_operation for each operation it picks, then execute_operation once for the lookup and once for the tag. The connection is bound to your account/location, so the assistant doesn’t need a location id.

Behind the four tools sits a catalog of hundreds of read, create, update and delete operations. It covers contacts, conversations and messages, opportunities and pipelines, calendars and appointments, payments, products and store, invoices, estimates and documents, the social planner, blogs, emails, forms and surveys, funnels, workflows, Voice AI, the phone system, knowledge bases, the media library, custom objects and associations, businesses and team members, and more. Ask the assistant to search operations for the exact list your connection can use.

Write, delete and money-movement operations pass through extra confirmation and safety checks before they run. describe_operation shows an operation’s safety information first, and execute_operation accepts dryRun: true to preview a call without running it.

Connect with a Private Integration Token

Section titled “Connect with a Private Integration Token”

Clients that let you set request headers can connect to /mcp/ with a Private Integration Token. It’s built for server-to-server use, it’s already scoped to your account/location, and there’s no browser sign-in.
URL https://services.smbcrm.com/mcp/
Transport Streamable HTTP
Auth Authorization: Bearer <pit-token>
Account/location Provide your <location_id> (see below)

This endpoint exposes a fixed set of tools, one per operation, in these areas: contacts, conversations, opportunities, calendars, blogs, the social planner, payments (orders and transactions), email templates, and your location’s details and custom fields. For anything else, call the REST API with the same token, or use a signed-in connection.

Providing your account/location

Section titled “Providing your account/location”

Most tools on /mcp/ take a required locationId argument. Provide your <location_id> in whichever way your client supports:

  • as a header on the connection, for example locationId: <location_id>, or
  • in the agent’s prompt or tool arguments when it calls a tool.

Send the header and also tell the agent your location id in its instructions, so it can fill in the locationId argument. Tools that act on a single record by id, such as getting or updating one contact, don’t take a locationId argument.

Configure your client

Section titled “Configure your client”

Most MCP clients take an HTTP server URL plus headers. The config shape varies by client; the values are always the same: the URL, your token, and your location id.

{
  "mcpServers": {
    "smbcrm": {
      "type": "http",
      "url": "https://services.smbcrm.com/mcp/",
      "headers": {
        "Authorization": "Bearer <pit-token>",
        "locationId": "<location_id>"
      }
    }
  }
}

Check the connection

Section titled “Check the connection”

Once the client is connected, ask the assistant to list five contacts from your account. This needs the contacts.readonly scope.

If something fails, match the symptom:

  • “This MCP client must use /mcp/openai/v2” (or another client’s path). The client is connected to another client’s URL. Use the URL for your client from the table above.
  • “This MCP client is not recognized”. The URL doesn’t accept sign-in from this client. Check that you used the URL for your client. If you did, connect with a Private Integration Token instead.
  • “Unknown client_id. Create the custom MCP connection again to register a new client.” Remove the connector from your AI client and add it again.
  • A token client opens a sign-in window or reports an authorization-discovery error. The server didn’t receive a Private Integration Token. Check the header name, the Bearer prefix, that the value is the full token (it starts with pit-), and that your client supports custom headers.
  • A token client connects but tools return Invalid Private Integration token. The server checks the token when a tool runs, not when the client connects, so a wrong token still connects. The token is wrong, has expired, or belongs to an integration that was deleted.
  • One area fails while others work. The connection lacks that area’s scope. For a token, edit the integration to add it; the existing token keeps working.

Scope guidance

Section titled “Scope guidance”

A tool call succeeds only if the connection carries the matching REST scope. To let an agent create contacts, it needs contacts.write; to read the calendar, calendars/events.readonly. For token connections, grant the smallest set of scopes for what the agent should do, and issue a separate token per agent so you can expire or delete one without affecting the others.

On a signed-in connection, the operations the assistant can find depend on the scopes you approved, and describe_operation reports the scopes an operation needs before the assistant runs it.

Section titled “Related”