Skip to main content

MCP server

Vehiso runs a Model Context Protocol server, so an AI assistant can look up stock, enquiries, customers, appointments and deals, and make a set of everyday stock changes (price, status, website visibility and details), on a dealer's behalf.

URLYour dealership's own URL, https://api.vehiso.com/v1/dealers/{dealer id}/mcp, shown in the DMS under Administration > Developers. https://api.vehiso.com/v1/mcp also works.
TransportStreamable HTTP, JSON responses
Protocol version2025-06-18 (2025-03-26 and 2024-11-05 are also accepted)
AuthenticationOAuth sign-in (for Claude's connectors and other apps), or Authorization: Bearer <key> with a secret key. Publishable keys cannot use it.

The server uses the same services as the REST endpoints, so it follows the same rules: the key's scopes, its owner's permissions, branch restrictions and rate limits all apply.

Two ways to connect​

  • Sign in with OAuth. Claude on the web, desktop and mobile, and most MCP apps, only connect this way: you give them the URL, they send you to the Vehiso DMS (Dealer Management System) to approve, and they never see a key. Use this unless your client asks for a header.
  • Paste a secret key. For clients that let you set a request header, such as Claude Code or mcp-remote. See Choose a key.

Claude (web, desktop and mobile)​

Claude's connectors cannot take an API key, so they use OAuth.

  1. In the DMS, open Administration > Developers and copy the AI assistant (MCP) URL. It names your dealership.
  2. On claude.ai or in Claude Desktop, open Settings > Connectors and choose Add custom connector. (The mobile app cannot add one; add it on the web or desktop and it then works on your phone.)
  3. Name it Vehiso and paste the URL. Leave the advanced OAuth settings empty.
  4. Choose Connect. You are taken straight to your own DMS (sign in if you are not already), and shown what Claude is asking to do. Approve it.
  5. Turn the connector on in a chat, and ask, for example, "Which vehicles have been in stock the longest?".

The consent screen says Vehiso has not reviewed the app. That is expected: Claude registers itself as an app when you connect, which is how every MCP client connects. Approve only a connection you started yourself, and check it sends you back to claude.ai.

Claude asks for every scope. What it can do is still limited by your own role in the DMS, so connect as a user whose access you are happy for the assistant to have. The connection appears under Administration > Developers as a connected app, where you can revoke it at any time.

How the OAuth connection works​

For other clients, or if you are building one: a request to /v1/mcp without a token answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api.vehiso.com/.well-known/oauth-protected-resource/v1/mcp" (RFC 9728). That document names https://api.vehiso.com as the authorisation server, whose metadata is at /.well-known/oauth-authorization-server (RFC 8414). The client registers itself at POST /v1/oauth/register (RFC 7591), usually as a public client with no secret, then runs the authorisation code flow with PKCE. A self-registered client may leave out scope, which asks for every scope it registered for. When the client sends the dealer's URL as resource (RFC 8707), as MCP requires, the dealer is sent straight to their own DMS to approve; with /v1/mcp they first sign in centrally and give their dealer code. A token used at another dealer's URL is refused with 403 wrong_dealer.

Choose a key​

Create a secret key in the DMS under Administration > Developers just for the assistant (a partner app can use its OAuth access token instead), so you can see its usage separately and revoke it on its own. Give it only the scopes the assistant needs. Every tool is filtered by scope: a tool whose scope the key lacks is simply not offered. A read-only key (only :read scopes) gives a read-only assistant.

Use a test key (vh_test_sk_...) first to try it against your sandbox.

Available tools​

ToolScopeWhat it does
search_vehiclesvehicles:readLists vehicles, filtered by status, make, model, registration or website visibility.
get_vehiclevehicles:readOne vehicle with its full details and photos.
update_vehicle_pricevehicles:writeSets the asking price in minor units, or marks it price on application.
change_vehicle_statusvehicles:writeMoves a vehicle to another stock status, such as IN_STOCK, RESERVED or SOLD.
set_vehicle_website_visibilityvehicles:writeShows or hides a vehicle on the website. The website shows it only while it is IN_STOCK or RESERVED.
update_vehicle_detailsvehicles:writeEdits details such as mileage, colour, description, MOT expiry or VAT scheme. Price, status and website visibility have their own tools.
stock_summaryvehicles:readHow many vehicles are in each status, and the asking value of stock on sale.
list_enquiriesenquiries:readLists enquiries, filtered by status.
get_enquiryenquiries:readOne enquiry with its notes.
create_enquiryenquiries:writeRecords a lead; takes the POST /v1/enquiries body.
search_customerscustomers:readFinds customers by email or phone.
list_appointmentsappointments:readAppointments, optionally between two dates.
list_dealssales:readSales deals.
request_website_themewebsite_themes:writeStarts a website theme build from a brief, or a revision of the last one. It does not go live by itself.
get_theme_generationwebsite_themes:readA theme build's status, with a preview link once it has succeeded.

A tool is listed only when the key has its scope. Each tool describes its own inputs to the client, so the assistant knows how to call it. When a tool refuses (a validation failure, a record that does not exist), it answers with a result whose isError is true, so the model can read the reason and correct itself.

Claude Code​

claude mcp add --transport http vehiso https://api.vehiso.com/v1/mcp \
--header "Authorization: Bearer vh_live_sk_..."

Then ask, for example, "Which vehicles have been in stock the longest?". Run /mcp inside Claude Code to check the connection.

Claude Desktop with a key​

Prefer the connector above. If you need a key instead, Claude Desktop connects to remote servers that need a custom header through the mcp-remote bridge, which needs Node.js installed. Open Settings > Developer > Edit Config and add:

claude_desktop_config.json
{
"mcpServers": {
"vehiso": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://api.vehiso.com/v1/mcp",
"--header",
"Authorization:${VEHISO_AUTH}"
],
"env": {
"VEHISO_AUTH": "Bearer vh_live_sk_..."
}
}
}
}

Restart Claude Desktop. The Vehiso tools appear in the tools menu. (Writing the header as Authorization:${VEHISO_AUTH}, with the value in env, avoids a quoting problem with spaces in arguments on some platforms.)

Other MCP clients​

Any client that supports the streamable HTTP transport and MCP's OAuth sign-in can connect with just the URL. A client that takes custom headers instead can point at https://api.vehiso.com/v1/mcp and send Authorization: Bearer <key> on every request. For clients that only launch local (stdio) servers, use mcp-remote as above.

The server supports the initialize, ping, tools/list and tools/call methods. Each request body is one JSON-RPC 2.0 message; batches are not supported. A notification (a message with no id) is acknowledged with 202 and no body. The server sends nothing unprompted, so GET /v1/mcp, which would open a server-sent event stream, answers 405 as the MCP specification provides.

To check a key by hand, send an initialize request:

curl https://api.vehiso.com/v1/mcp \
-H "Authorization: Bearer $VEHISO_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Then list the tools the key can use:

curl https://api.vehiso.com/v1/mcp \
-H "Authorization: Bearer $VEHISO_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "MCP-Protocol-Version: 2025-06-18" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Protocol errors use JSON-RPC error codes inside a 200 response: -32700 parse error, -32600 invalid request, -32601 unknown method and -32602 unknown tool.

Keeping it safe​

  • A connector signed in with OAuth acts as the DMS user who approved it, with that user's role. Revoke it under Administration > Developers when it is no longer needed.
  • Tools that change data (price, status, website visibility, details) are marked as such, so clients like Claude ask before running them. Check what the assistant proposes before you approve it.
  • The assistant can do anything the key's scopes allow. Leave out write scopes unless you want it to change data, and leave out personal-data scopes (enquiries, customers, sales, appointments) unless it needs them.
  • The key sits in the client's configuration file on that computer. Treat that file like a password, and revoke the key in the DMS if the computer is lost.
  • Every call appears in the dealer's request log in the DMS, like any other API request.