Should an agent use MCP or REST?

Agents use MCP and sign in with OAuth. Scripts and backends use REST with an API key. Both run the same scoring engine.

How do I authenticate REST calls?

Send an API key in x-api-key or in Authorization: Bearer. Create keys on /keys after an email sign-in. GET /api/health needs no auth.

Which calls count toward the Free meter?

Free includes 5 scored deals per UTC month. Only results with coverage: scored count, and MCP, REST, and /try share one counter. cannot_score results and validation errors do not count.

What happens over the cap?

POST /api/score returns 402 with an upgrade payload. The MCP score_deal tool returns a tool error.

What does POST /api/explain do?

It maps a delta_pct value to a grade without scoring a car.

Docs

API reference

DealScore runs one scoring engine behind two interfaces: MCP Streamable HTTP at https://cardealscore.com/api/mcp for agents, and REST at POST /api/score for scripts and backends. Connecting an agent? Start at /agents. To test arguments by hand, use /try.

For agents

DealScore is a remote MCP server plus a small REST API. Discovery files are public JSON (no auth, no secrets):

MCP Streamable HTTP: https://cardealscore.com/api/mcp
Server card: /.well-known/mcp/server-card.json
API catalog: /.well-known/api-catalog
Agent skills: /.well-known/agent-skills/index.json
OAuth resource: /.well-known/oauth-protected-resource
OAuth server: /.well-known/oauth-authorization-server
Auth: /auth.md
Agent summary: /llms.txt
Health: GET /api/health (no auth)

Cursor-style MCP config (OAuth preferred):

{
  "mcpServers": {
    "dealscore": {
      "url": "https://cardealscore.com/api/mcp"
    }
  }
}

API key config remains for curl, scripts, and clients that cannot do OAuth:

{
  "mcpServers": {
    "dealscore": {
      "url": "https://cardealscore.com/api/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

REST endpoints:

POST /api/score: grade a deal
POST /api/explain: map delta_pct to a grade
GET /api/health: service health (no auth)

Auth for REST (and MCP clients that still use keys):

x-api-key: YOUR_KEY
Authorization: Bearer YOUR_KEY

Usage meter

Live scores share one Free meter per signed-in user: 5 deals per UTC month that return coverage: scored. MCP, REST, and the /try playground increment the same counter. cannot_score and validation errors do not count. Over the cap, POST /api/score and POST /api/internal/score return 402 with an upgrade payload. MCP score_deal returns a tool error. There is no silent mock.

Builder is $19/mo (founding price) for 1,000 scored calls a month. See /pricing.

Get a key

Sign in with an email magic link, then create or revoke keys on /keys. The /try playground uses the same signed-in Free meter as these keys.

Sign in to create an API key (email magic link). Create and revoke keys on /keys. Live scores share a Free meter of 5 scored deals per month across MCP, REST, and the /try playground.

Base URL

Production: https://cardealscore.com.

Authentication

MCP clients should use OAuth (add /api/mcp, sign in in the browser). See /auth. POST /api/score and POST /api/explain use API keys. Send either:

x-api-key: YOUR_KEY
Authorization: Bearer YOUR_KEY

GET /api/health is open. In local dev with no keys configured, programmatic routes work without auth.

Sign in to create an API key (email magic link). Create and revoke keys on /keys. Live scores share a Free meter of 5 scored deals per month across MCP, REST, and the /try playground.

Endpoints

GET /api/health

No auth. Env and mode check.

curl -sS https://cardealscore.com/api/health

POST /api/score

Score a deal. YMM or VIN + price + mileage. ZIP is optional.

Example output, illustrative numbers. Score a real listing.

curl -X POST https://cardealscore.com/api/score \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "year": 2019,
    "make": "Example",
    "model": "Sedan",
    "asking_price": 20000,
    "mileage": 40000
  }'

POST /api/explain

Map a delta_pct to grade without scoring.

curl -X POST https://cardealscore.com/api/explain \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{ "delta_pct": -0.08 }'

POST /api/mcp

MCP Streamable HTTP. OAuth for agents; API keys still work. Tools: score_deal, explain_grade, health.

{
  "mcpServers": {
    "dealscore": {
      "url": "https://cardealscore.com/api/mcp"
    }
  }
}

Response fields (score)

Key fields in a successful score:

grade, score, delta_pct: score_v2 rubric
expected_price, expected_price_low/high : expected market value band from comps
comps_count, data_source (live | mock | error), coverage (scored | cannot_score | partial)
brief, risks, confidence

Quick answers

Should an agent use MCP or REST?: Agents use MCP and sign in with OAuth. Scripts and backends use REST with an API key. Both run the same scoring engine.
How do I authenticate REST calls?: Send an API key in x-api-key or in Authorization: Bearer. Create keys on /keys after an email sign-in. GET /api/health needs no auth.
Which calls count toward the Free meter?: Free includes 5 scored deals per UTC month. Only results with coverage: scored count, and MCP, REST, and /try share one counter. cannot_score results and validation errors do not count.
What happens over the cap?: POST /api/score returns 402 with an upgrade payload. The MCP score_deal tool returns a tool error.
What does POST /api/explain do?: It maps a delta_pct value to a grade without scoring a car.

Agent-oriented summary: llms.txt. OAuth discovery: /.well-known/oauth-protected-resource. MCP discovery: /.well-known/mcp/server-card.json. Guides: VIN scoring, how grades work, is this car a good deal, scoring with an agent, car price APIs compared, DealScore vs KBB vs CarGurus. Data: used-car recalls by model. Claude Desktop setup, Cursor, VS Code, Claude Code, Codex, ChatGPT, n8n, and the used car price API.