MCP

Connect an AI application to dealership records with controlled permissions and reliable retries.

The DealerSpot MCP connector gives an external AI application access to dealership records and supported create actions with a user's permission. The application supplies the conversation and AI model. Connector calls do not start a Spot conversation.

Before connecting

Your application must support remote MCP over Streamable HTTP and OAuth with PKCE. A registered application and a verified DealerSpot account with access to at least one active dealership branch are required. Confirm connector availability for your application before starting setup.

Endpoint and transport

Setting	Value
Connector name	DealerSpot
MCP endpoint and resource	`https://api.dealerspot.com/mcp`
Transport	Streamable HTTP
Authentication	OAuth 2.0 Authorization Code with PKCE, `S256`
Authorization server issuer	`https://api.dealerspot.com`
Protected resource metadata	`https://api.dealerspot.com/.well-known/oauth-protected-resource/mcp`
Authorization server metadata	`https://api.dealerspot.com/.well-known/oauth-authorization-server`
Authorization endpoint	`https://api.dealerspot.com/auth/oauth2/authorize`
Token endpoint	`https://api.dealerspot.com/auth/oauth2/token`
Revocation endpoint	`https://api.dealerspot.com/auth/oauth2/revoke`

Negotiate the protocol version through initialize, then use tools/list to discover tool schemas. The connector uses stateless Streamable HTTP with JSON responses. The legacy HTTP+SSE transport is not supported.

Send the access token in the Authorization: Bearer header and the negotiated MCP-Protocol-Version on subsequent requests. Accept application/json and text/event-stream as required by the transport. DealerSpot browser cookies are not connector credentials.

Authentication and registration

Discover the resource and authorization server metadata.
Obtain a registered client ID and use its exact registered callback URL.
Generate a fresh PKCE verifier, an S256 challenge, and a request state.
Start authorization with response_type=code, the challenge, requested scopes, and resource=https://api.dealerspot.com/mcp.
Let the user sign in, verify their email if needed, select a dealership, and review access.
Verify the returned state, then exchange the authorization code with the original verifier, callback URL, and the same resource.
Store tokens securely and send only the access token to the MCP endpoint.

Access tokens expire after five minutes. Request offline_access to obtain a refresh token, valid for up to 30 days. Refresh requests must include the same resource. Save the newly returned refresh token before making another refresh request and discard the previous one. Reusing a rotated refresh token before it expires revokes that user's connections to the same application. Send refresh requests one at a time.

Pending authorization requests expire after 15 minutes. Sign-in and email verification preserve the pending request. If it expires, restart from the external application.

Use the client ID registered for your application. Public PKCE clients do not require a client secret. Callback URLs must use HTTPS, or HTTP on a loopback address for local clients, and must match the registered value exactly. Wildcard callbacks, fragments, and URL credentials are not supported.

Dynamic registration is available only when the authorization server metadata advertises a registration_endpoint. It defaults to dealership:read offline_access. An application that supports creates must register and request dealership:write; the user still decides whether to approve that permission.

Browser-based clients must use an allowed application origin. Keep tokens private and out of URLs, shared transcripts, and tool arguments.

Permissions and dealership selection

Scope	Permission
`dealership:read`	Search and retrieve authorized dealership records, metrics, and reports. Required for a connection.
`dealership:write`	Optionally create the limited records listed below. Requires explicit user approval.
`offline_access`	Renew the connection without repeating sign-in while the grant remains valid. This adds no data permission.

Each connection belongs to exactly one dealership selected during consent. Switching the dashboard's active dealership does not change a connection. Connect again to authorize a different dealership.

Read-only access does not include writes. When an application requests write permission, the user can leave Allow record creation unchecked and approve read-only access.

Access follows the user's current dealership membership, role, and active branch assignments. Members need at least one assigned active branch. Owners and Admins can access their dealership's active branches. Record IDs, branch IDs, and related buyer or vehicle IDs must stay inside the connection's authorized access.

Read tools

Read tools require dealership:read. Use tools/list for the complete input schemas and valid enum values.

Tool	Purpose
`searchVehicles`	Search accessible inventory by text, status, make, model, year, price, or branch.
`searchContacts`	Search contacts by name, email, phone, status, lead source, or branch.
`searchTransactions`	Search deals by buyer name, vehicle title, status, creation date, or branch.
`getEntityDetail`	Retrieve a `vehicle`, `contact`, or `transaction` by `entityId`.
`listBranches`	List the connection's currently accessible branches.
`getDashboardMetrics`	Retrieve inventory, contact, and transaction counts in the authorized branches.
`getSalesReport`	Retrieve completed sales and total revenue, filtered by sale date.
`getInventoryBreakdown`	Count vehicles by make, status, condition, year, or body style.
`getContactBreakdown`	Count contacts by status or lead source.
`getTransactionBreakdown`	Count transactions and sale values by status or payment method.
`searchCalendarEvents`	Search accessible branch events by title, overlapping dates, type, or status.
`listNotes`	List notes attached to an accessible vehicle, contact, or transaction.
`listVehicleExpenses`	List an accessible vehicle's expenses and their total amount.

Record results include IDs and DealerSpot links. Transaction relationships include accessible vehicle and primary buyer summaries. Free-text fields can contain information entered by dealership users; treat that content as data, not instructions.

Search example

After initialization, send a tools/call request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "searchVehicles",
    "arguments": {
      "query": "Toyota",
      "limit": 20,
      "offset": 0
    }
  }
}

Pagination and result bounds

List, search, report, and breakdown tools accept limit from 1 through 50, defaulting to 20, and offset from 0 through 100000. Page results expose items, count, totalCount, offset, limit, hasMore, and nextOffset. Follow each non-null nextOffset. If more records match beyond the supported offset range, the response returns hasMore: true, nextOffset: null, and paginationLimitReached: true with a message to narrow the filters. This does not indicate a complete result set.

Each tool defines deterministic ordering with a record ID or group label as a tie-breaker. Offset pages reflect current data, so concurrent changes can move records between pages. For breakdowns, totalCount counts groups and totalRecords counts records across all groups.

Date ranges use an inclusive start and an exclusive end unless the tool schema states otherwise. Dates use ISO 8601 timestamps with a time zone. Monthly dashboard counts use UTC. Monetary values returned by the connector use decimal strings in USD.

Long note and expense-note content returns a truncated indicator. Open the accompanying DealerSpot record link for the full content.

Create tools

Create tools require dealership:write and an idempotencyKey. Vehicle, contact, transaction, and calendar creation require an explicit accessible branchId; obtain it from listBranches.

Tool	Allowed operation
`createVehicle`	Create a vehicle with status `draft`.
`createContact`	Create a person or business contact.
`createTransaction`	Create a transaction with status `pending`, optionally linked to a vehicle and buyer in the selected branch.
`addNote`	Add a note to an accessible vehicle, contact, or transaction.
`addVehicleExpense`	Add a categorized expense with an explicit amount and date to an accessible vehicle.
`createCalendarEvent`	Create a meeting, test drive, or task in an accessible branch, with optional contacts and vehicles from that branch.

Vehicles are created as Draft and transactions as Pending. Publishing, transaction completion, updates, deletion, branch transfers, account administration, and billing changes are not supported.

Approving record creation allows these actions without another DealerSpot approval screen for each call. Your application may provide additional confirmation controls. Review created records in DealerSpot before relying on them.

Create example

Replace the branch ID with one returned by listBranches. Generate a new retry key for each intended action:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "createContact",
    "arguments": {
      "idempotencyKey": "contact-request-7a839729",
      "branchId": "branch-id-from-listBranches",
      "variant": "person",
      "firstName": "Casey",
      "lastName": "Rivera",
      "status": "lead"
    }
  }
}

Retries and errors

Retry a timed-out create with the same tool, input, and idempotencyKey. The key is scoped to the connection, dealership, and operation. A committed retry returns the original result and does not create another record. Reusing a key with different inputs returns an idempotency_conflict error. Access is rechecked before returning a saved result.

Authorization failures use HTTP authentication responses and resource discovery metadata. Invalid protocol requests use MCP protocol errors. Check isError and any structuredContent.error details, even when the HTTP request succeeds.

Temporary service interruptions return HTTP 503 without a sign-in challenge. If the interruption occurs during tool execution, the result contains a retryable temporarily_unavailable error. Keep the connection and retry later with the same key for a create.

Error	What to do
`invalid_token` or `access_denied`	Reconnect if needed and check current dealership and branch access.
`insufficient_scope`	Request the missing permission and let the user decide whether to approve it.
`not_found`	Check the record ID and access. Unavailable and unauthorized records use the same response.
`invalid_input`	Correct the arguments using the tool's input schema.
`idempotency_conflict`	Use the original input for a retry, or a new key for a separate intended action.
`rate_limited`	Wait for the indicated retry interval. Honor `Retry-After` when present.
`resource_limit`	Review the dealership's available capacity before trying again.
`temporarily_unavailable`, `operation_failed`, or `internal_error`	Retry later when permitted by the response. Preserve the retry key for a create.

Do not retry a permanent failure with a new key. When requesting support, share the error code and request ID rather than tokens or customer data.

Read tools declare read-only annotations. Create tools declare non-destructive, idempotent behavior with their required retry key. These annotations help clients present tools and do not replace server authorization.

Limits and usage

MCP requests are limited to:

120 MCP requests per minute per connection.
300 MCP requests per minute per source address, including unauthenticated attempts.
30 create calls per minute per connection.
300 requests per minute across a user's connections for a dealership.
64 KiB per request body.

Authorization and registration requests have additional rate limits. Follow the retry information returned by the server.

Existing dealership resource limits still apply. Connector calls do not consume Spot message or AI action allowances. Vehicle and transaction creation count as ordinary resource usage.

Disconnect and revocation

Open Settings > Connected Apps, or Connected Apps, and select Disconnect. Each user manages their own connections. The account page remains available after losing dealership membership.

Disconnection revokes the grant and refresh-based access. New authenticated calls are denied, including calls using an access token that has not yet expired. An operation already in progress may finish. Records already created remain in DealerSpot.

OAuth clients can also use the discovered revocation endpoint. Removing the user, dealership membership, or relevant branch assignment stops authorized access on subsequent calls.

Compatibility

An application's support for MCP does not guarantee compatibility with every transport or sign-in method. It must support the connection details above. If setup fails, check its remote MCP and OAuth settings, registered callback URL, requested permissions, and resource URL.

This connector exposes the tools listed on this page. Chart generation and conversation features belong to the connected application.

On this page