MCP & agents

Remote and local MCP, Claude Code, ChatGPT actions.

Remote MCP server

The hosted server speaks MCP over Streamable HTTP. Point any MCP host at it — nothing to install. Hosts that speak OAuth (Claude Code, Codex, Cursor, chat connectors) need only the URL and sign in with the browser; others send your key in the Authorization header, as below. In Claude Code, use the commands further down: an Authorization header there turns browser sign-in off.

POST/api/mcp

Bearer key or OAuthper tool

mcp.json

{
  "mcpServers": {
    "car-image": {
      "url": "https://carimage.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${CAR_IMAGE_API_KEY}"
      }
    }
  }
}

Endpoint: https://carimage.dev/api/mcp exposes the eleven core tools; https://carimage.dev/api/mcp?toolset=all adds make logos, 3D models, image options, the API reference, pricing, help and billing links. Most hosts expand ${CAR_IMAGE_API_KEY} from your environment; if yours does not, keep the config file out of version control.

Claude and ChatGPT connectors (no key)

A chat client has nowhere to put an API key mid-conversation, so it uses OAuth instead. Add this URL as a custom connector: the client discovers this server, registers itself, and opens a browser tab where you sign in and approve. There is nothing to copy, paste or rotate.

Connector URL

https://carimage.dev/api/mcp

In Claude: Settings → Connectors → Add custom connector, paste the URL. In ChatGPT: Settings → Apps & Connectors → Create (developer mode), paste the URL and choose OAuth. No client id or secret: the client registers itself.
Sign in and approve on carimage.dev. The screen names the app, the account, your balance and exactly what it will be able to do.
Ask for a car image. Renders are billed to your credits, one per image, and your dashboard lists the connection with a Disconnect button.

A connector is granted images:read and account:read, and it can never do something the consent screen did not list. See OAuth for connectors for how discovery works and who issues the tokens.

No account yet: the catalog server

A second hosted server needs no sign-in and no key, because nothing on it renders, bills or reads an account: resolve_vehicle, search_vehicles, list_image_options, get_pricing, search_help (the help center: pricing, licensing, what happens when a plan ends) and describe_api, plus preview_car_image, which returns the picture a vehicle's page on carimage.dev/cars already shows, free, with Markdown ready for a chat reply. It never renders and never recolors: another view, paint or size is an image from the server above.

POST/api/mcp/catalog

Nonefree

bash

claude mcp add --transport http car-image-catalog https://carimage.dev/api/mcp/catalog

The plugin connects it next to the account server, so an agent can look a car up, show the preview and explain the API from the first session, and ask for sign-in only when the person wants an image the catalog does not hold. Its instructions tell the agent how: in Claude Code, the authenticate tool Claude Code lists for a server that needs sign-in, or /mcp. Once the account tools appear, the agent finishes the request it was given. Tool calls are limited per address; the URL is https://carimage.dev/api/mcp/catalog.

Tools

The server exposes two toolsets. Core, the default, is what an agent needs to look a vehicle up, render it and watch the balance: eleven tools. Fewer tools mean less context on every turn and a better pick when the agent chooses one, so make logos, 3D models, image options, the API reference, pricing, help and billing links are opt-in: append ?toolset=all to the URL, or run car-image mcp --toolset all for the stdio server. Connectors get the core set because their URL is the bare resource; the plugin registers ?toolset=all so its skills keep working.

A picture of a car is two calls. The agent looks the vehicle up first (resolve_vehicle for a name, decode_vin for a VIN, search_vehicles to browse, check_vehicles for a whole list; all free), then shows it by the vehicle id it was given (create_car_image_urls, whose Markdown goes in a chat reply and whose URL goes in a page; get_car_image for a file or bytes). The catalog files cars under its own names, so a make and model an agent types from memory can miss a car the catalog carries: a 2018 Mazda MX-5 Miata is mx-5. The server's instructions say this in their first 2,048 characters, with the costs and the rule that a 402 goes to the human, because that is as much of them as some hosts pass to the model. Some hosts also pass a tool's arguments on as text: both servers read "true", "960" and the JSON of a list as the flag, the number and the list the tool advertises, and refuse anything else as before.

All thirty-nine tools

https://carimage.dev/api/mcp?toolset=all

Core (default)

Tool	Cost	Description
`resolve_vehicle`	free	The first call for any picture of a car: turn a phrase ("blue 2022 bmw m3 side profile") into the catalog vehicle and exact request parameters including the vehicle id, with alternative candidates and a confidence of high, medium or low. A make and model are read by the rules the image tools use, so it names the vehicle they would render.
`search_vehicles`	free	Browse the catalog for makes and models; returns available years, and a vehicle id per year, so the agent can list a make's models or let the human pick between variants.
`decode_vin`	free	Decode a full or partial VIN (NHTSA vPIC): year, make, model, trim, engine, plant and every vPIC attribute, plus the catalog vehicle id and image path when the car is in the catalog.
`check_vehicles`	free	Check a list of up to 100 vehicles in one call, each as make, model and year or a stored id: every entry comes back as a match with the vehicle id to render by, a suggestion (the same model in its nearest year, a related model; never substituted), a miss or an invalid entry, read exactly as the image tools would read it. Longer lists go through the CLI's check command or the SDK, 2,000 per request.
`get_car_image`	1 credit	Return an MCP image attachment for explicit file or byte requests; use create_car_image_urls to display images in chat. Includes usage metadata for a vehicle id (from resolve_vehicle, search_vehicles or decode_vin) or a make/model/year, in a view and a color (a preset name or any hex), at any width and height with fit, background, a framing preset or trim and padding, and an optional ground shadow. format auto is accepted and delivers PNG inline; only a signed URL can negotiate per viewer.
`create_car_image_urls`	1 credit per URL	Mint up to 50 signed URLs with a TTL, an optional use cap or auto-renewal (renew, renew_days) and the same sizing options (format auto negotiates WebP or PNG per viewer), for inline chat images or embedding in a page or document. Paste each returned data[].markdown directly into the reply, outside code fences; state expiry. For chat use a 7-day TTL, unlimited uses and renewal off unless requested. Reuse URLs and do not call get_car_image first. Items take vehicle (an id) and hex colors too. Pass idempotency_key when the call might be repeated: a retry with the same key and arguments replays the first result (idempotent_replayed: true) instead of billing again.
`get_account`	free	Credit balance, auto-reload state and pricing — call it before large batches.
`request_feature`	free	File a feature request on the public feedback board. Similar items come back first and nothing is filed until force: true, so an agent upvotes a match instead of a duplicate. The human gets a thank-you and an email at every status change.
`report_issue`	free	Report a problem with Car Image with the failed call's request_id and context (endpoint, error code, vehicle id, view, color) attached; private to the human and the team, checked against the account's own requests.
`upvote_feedback`	free	Vote for a feature, vehicle request or published issue (idempotent); the human follows it and hears when it ships.
`submit_review`	free	Post or edit the human's public review (1-5 stars, their own words; never invented). Shown on /reviews with the team's answer.

With `?toolset=all`

Tool	Cost	Description
`list_feedback`	free	The feedback board: features, vehicle requests and published issues with votes, status and page URLs; search with q, sort by top, new or recent_activity.
`get_feedback`	free	One item with its comments (official responses marked), timeline of status changes and, for the reporter's own issue, its context.
`list_my_feedback`	free	What the human filed, voted on, commented on or follows, with each item's status.
`remove_feedback_vote`	free	Remove the human's vote; they stop following unless they commented.
`comment_on_feedback`	free	Add a comment (first name shown, never an email).
`list_reviews`	free	Published reviews with the team's answers, the average rating and the 1-5 distribution.
`get_make_logo`	1 credit	Inline catalog make logo, with size, width, height, fit, background, trim, padding and format. auto returns PNG; no signed URL mode. Third-party trademarks for referential display only; no license or VehiclesDB indemnity. Inspect generated logos before use.
`create_3d_model`	100 credits	Request a textured 3D model (GLB, USDZ, FBX, thumbnail and a browser build) of a vehicle in a color; charged at creation, cached or not, and free for a vehicle and color the account already owns. publish: true gives it key-free URLs and a two-line embed at once. Returns the request id and status; the first model of a vehicle takes 10–20 minutes.
`get_3d_model`	free	Status, progress, file URLs and, once published, the public URLs and embed of a 3D request; poll it until status is ready.
`publish_3d_model`	free	Give a 3D request key-free URLs and a two-line <car-3d> embed hosted by Car Image, or take them down again with unpublish: true. Works before the model is ready.
`list_image_options`	free	Valid views (with yaw degrees), preset colors and the hex paint rule, size presets, fits, backgrounds, formats and the vehicle-id format.
`describe_api`	free	A compact description of endpoints, costs and rules for agents that were not given these docs.
`get_pricing`	free	Current monthly and yearly plans, allowances, credit packs and live 3D model cost.
`search_help`	free	Source-linked product, licensing, policy and Enterprise articles. Questions are recorded privately; omit secrets and personal data. Set report_gap when the articles leave a question unanswered.
`create_checkout_link`	free	Prepare a credit-pack or subscription link on the human’s request. No charge or immediate plan change; the human confirms in the browser. Connected apps and existing subscriptions use the dashboard.
`get_billing_link`	free	Open billing settings: a private Stripe portal for owner keys with billing:write, or a dashboard sign-in link for connected apps.
`checkout_status`	free	The state of a Checkout session from create_checkout_link (its session_id): poll until complete when an agent pays in the browser with an agent card or Link.
`purchase_plan`	the plan's price	Buy Pro or Business with a Stripe Shared Payment Token (spt_…), never a card number. Only for a key with billing:purchase and within the owner's monthly agent spending limit; dry_run first, purchase_id to retry safely. Refusals return checkout_url.
`pay_invoice`	the invoice amount	Pay an open plan invoice (a renewal a one-time token could not pay) with a fresh payment token, within the same limit.
`list_members`	free	The organization's members and teams with their roles, read only. Invites, removals and role changes stay on the dashboard.

Tool errors carry the same status, detail and request_id as the REST API, so the agent can follow the error reference.

When a lookup finds no match, the agent says the catalog does not carry the vehicle and stops; no other car is substituted. describe_api, get_pricing and search_help answer questions about the API, prices and terms; create_checkout_link and get_billing_link prepare links a person completes in the browser.

Claude Code, Codex and Cursor

Install the plugin instead

The plugin is the shortest path: it registers this server, the catalog server and seven skills that teach the agent when to use them, what a render or a 3D model costs and how to embed one without leaking your key. Two lines in Claude Code, Codex or Cursor; lookups and previews work at once, and browser sign-in through the host’s MCP controls comes when you want an image. The plugin does not require an API-key environment variable; in Claude Code, open /mcp and authenticate the Car Image server.

If you want the eleven core tools and none of the skills, one command adds the hosted server to Claude Code — nothing to install, nothing to keep up to date and no key (append ?toolset=all to the URL for all thirty-nine):

bash

claude mcp add --transport http car-image https://carimage.dev/api/mcp

Then run /mcp, select car-image and authenticate: Claude Code opens carimage.dev, where you sign in and approve. Ask for "a side view of a 2024 Porsche 911 in red", and /mcp lists the eleven core tools above.

For CI, or a machine without a browser, add it with an API key instead (npx @meterapp/car-image login prints one):

bash

claude mcp add --transport http car-image https://carimage.dev/api/mcp --header "X-Api-Key: $CAR_IMAGE_API_KEY"

The key goes in X-Api-Key on purpose. Claude Code turns browser sign-in off whenever an Authorization header is configured, even an empty one, so a server added with Authorization: Bearer $CAR_IMAGE_API_KEY while the variable was unset can never connect; remove it with claude mcp remove car-image and add it again.

For a project-scoped setup, a .mcp.json in the repository root with the URL and no key signs in the same way; npx @meterapp/car-image agent-config --host claude-code prints it, and the key form for CI.

ChatGPT actions

Create a custom GPT, add an action and import the OpenAPI document from https://carimage.dev/openapi.json. Choose Bearer authentication and paste a key with images:read. The schema declares every endpoint, parameter and problem response, so the action works without editing.

Machine-readable docs

/llms.txt — a compact guide to the API and its rules.
/agents.md — setup and safety behavior for autonomous agents.
/openapi.json — OpenAPI 3.1 with typed schemas.
/errors.md — the error reference as Markdown.

Rules for autonomous agents

Cost and retry behavior

Look a vehicle up before rendering it, and render by its id. Ask the human when the lookup is low confidence or answers in another year than the one asked for.
Do not retry a 402. Ask the human to approve a credit purchase.
Respect 429 and its Retry-After header; back off with jitter.
A capped delivery URL returns 410 after its last use; mint a new URL.
A 502 is refunded but consumes the delivery URL — mint a new one before retrying.
A 3D model costs 100 credits unless the account already owns that vehicle in that color: say so, and confirm, before calling create_3d_model.
Never present images as OEM photography; they are catalog-bounded studio renders.
Never move a key into a URL, a prompt or a tool result.

Core (default)

With ?toolset=all

With `?toolset=all`