Connect to the LeadTruffle MCP server

Connect ChatGPT, Claude, or another MCP client to read your LeadTruffle business data. Use OAuth sign-in in supported hosted apps, or supply a dedicated LeadTruffle API key in your own MCP client.

Private pilot: MCP is prepared for testing and requires an enabled LeadTruffle pilot deployment. It is not generally released or listed in the ChatGPT or Claude directories. These instructions do not indicate that a live connection has been verified.

Choose your connection

Every client uses the same MCP server URL:

https://pub-api.leadtruffle.com/mcp

The MCP address is separate from the REST API base URL, which ends in /api. Do not add /api or an API Gateway stage to the MCP address. A manual API-key connection does not require a ChatGPT account or an OAuth application.

Connect ChatGPT

1. Add a custom MCP server in ChatGPT and enter the MCP server URL above.
2. Select OAuth authentication. Use ChatGPT's published client identity when offered; the pilot also supports a preconfigured confidential client supplied by your pilot administrator.
3. Sign in with your existing LeadTruffle administrator account.
4. Check the business name, the ChatGPT app name, the return hostname and requested read permissions. Select Allow read access, or Cancel to leave access unapproved.
5. Return to ChatGPT and select the connection for your conversation.

Start with “Which contacts need a human?” or “Summarize this contact's stored conversation.” Follow returned page cursors when you need more results.

Custom connections depend on your ChatGPT account and workspace policy. The supported return URL is https://chatgpt.com/connector_platform_oauth_redirect. A different callback must be reviewed by the pilot administrator. See OpenAI's connection instructions.

Connect Claude

1. Add a custom web connector in Claude and enter the same MCP server URL.
2. Choose OAuth sign-in. Leave manually entered OAuth client credentials blank so Claude can use its published client identity.
3. Sign in to LeadTruffle as a business administrator.
4. Check that the consent page names Claude, shows your intended business, returns to claude.ai, and requests only the reads you want. Select Allow read access.
5. Return to Claude and enable the connection in your conversation.

The hosted callback is https://claude.ai/api/mcp/auth_callback. No separate Claude client secret is required. This covers the hosted connection flow, subject to your Claude account's connector policy. Directory publication is a separate review process. See Anthropic's connector authentication guide.

Claude Code can use the API-key connection below. Its separate loopback OAuth flow is outside this pilot.

Connect any compatible MCP client with an API key

In LeadTruffle, open Settings → API keys and create a dedicated key with only the read permissions your client needs. Keep it in your client's private settings or secret storage.

Select Streamable HTTP and configure these connection fields:

{
  "url": "https://pub-api.leadtruffle.com/mcp",
  "headers": {
    "x-api-key": "YOUR_LEADTRUFFLE_API_KEY"
  }
}

The surrounding configuration format differs between clients. If your client supports bearer authentication instead of custom headers, use this alternative:

{
  "url": "https://pub-api.leadtruffle.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_LEADTRUFFLE_API_KEY"
  }
}

Use one credential header. API keys in URL query parameters are not accepted. Do not share your key, commit it to source control, or substitute an OAuth client secret for it.

For example, Claude Code supports remote HTTP servers with a header:

claude mcp add --transport http leadtruffle https://pub-api.leadtruffle.com/mcp \
  --header "Authorization: Bearer YOUR_LEADTRUFFLE_API_KEY"

Clients supporting only local stdio processes need a trusted stdio-to-HTTP adapter. A legacy SSE-only client cannot connect directly. Server-side clients can connect without a browser Origin header; arbitrary browser origins are not automatically permitted. Use an approved browser origin or a server-side connector.

A key connects one business. The key's current permissions govern manual access; removing the user who created it does not revoke it. Disable or revoke the key in API keys to stop access. OAuth-managed credentials cannot be reused as manual keys.

Available read tools and permissions

The same tools are available to every connection. Each call requires the matching permission, approved through OAuth or granted to the manual key.

No tool sends messages, edits contacts, books appointments, changes AI settings or downloads recordings. A full-access API key does not add write tools to MCP. Empty or write-only keys cannot authenticate to this read-only server.

Search does not search message text. Lists return one page, with at most 50 records. Preserve nextCursor, partial-history indicators, unknown values, coverage, currency and the business reporting timezone when interpreting results. An empty page or unknown value is not evidence that a business has no history or revenue. Existing reporting eligibility and API limits still apply; see Inbox API coverage and analytics and revenue.

Consent, renewal and revocation

OAuth approval belongs to the administrator's current business. Agency-wide access and non-admin delegation are outside this pilot. Removing that administrator, changing their role, disabling their user/company or revoking the connection stops access and renewal. Increasing the backing credential's permissions cannot broaden the approved reads.

OAuth access tokens last 15 minutes and renew for up to 30 days before a new connection is required. A replayed or failed renewal can require reconnecting sooner. Refresh tokens rotate; clients must store the replacement supplied by the server.

For ChatGPT or Claude, open Settings → API keys → Manage MCP connections, identify the app and choose Revoke access. This stops that connection's reads and renewal without changing unrelated integrations. Remove the connector in the AI app separately if desired. Reconnect from that app to approve access again.

For manual clients, disable/revoke the dedicated API key in API keys. Revoking an OAuth grant does not revoke an unrelated manually created key.

Only data requested through a tool is returned to the connected AI app. MCP does not import your AI conversations or run a background contact sync. Review the AI app's own data policy before sharing business information.

Troubleshoot a connection

Protocol details

The endpoint accepts MCP JSON-RPC over POST using stateless Streamable HTTP with JSON responses. Initialization, tools/list and tools/call use the standard MCP SDK protocol. Initialization notifications return HTTP 202. There is no persistent MCP session or GET/SSE stream; authenticated GET and DELETE requests return HTTP 405.

Unauthenticated requests return HTTP 401 and a WWW-Authenticate header pointing to protected-resource metadata. OAuth discovery is available at https://pub-api.leadtruffle.com/.well-known/oauth-protected-resource and https://pub-api.leadtruffle.com/.well-known/oauth-authorization-server. The server supports authorization code with S256 PKCE and rotating refresh tokens for the supported ChatGPT/Claude identities. It does not offer arbitrary OAuth client registration or machine-to-machine grants. Use an API key for other clients.

For examples that call REST directly instead of MCP, use the API quickstart. For downloadable reference material, use docs for AI agents.