Skip to main content
Glama
sovorn-c

Vehicle Intelligence MCP Server

by sovorn-c
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

Vehicle Intelligence MCP Server

CI Python MCP

A read-only MCP server for evidence-preserving access to audited New Zealand vehicle records.

A canonical value is not enough when the underlying sources disagree. This server gives MCP clients the value, provenance, confidence, conflicts, revision history, and source observations needed to inspect the result.

The server is a typed integration layer over the NZ Vehicle Data Pipeline. The upstream pipeline is a deterministic data integration service that captures conflicting vehicle records across disparate sources (VPIC specifications, dealer feeds, fleet data, and risk registers), normalizes them, reconciles competing candidate values with field-level provenance and confidence scoring, and publishes immutable canonical revisions.

This MCP server exposes that evidence through six focused MCP tools without duplicating the pipeline's decision logic or connecting directly to the underlying database.

What the server provides

  • Evidence with every result: Canonical fields retain provenance, confidence, conflict state, and synthetic-data notices.

  • Explicit uncertainty: UNKNOWN, UNRESOLVED, and absent values remain distinct.

  • Point-in-time audit: Clients can inspect monotonic history and retrieve an exact immutable revision.

  • Controlled source access: Raw payloads appear only through an explicit source-observation lookup.

  • Transport parity: The same tool catalog and behavior are available over stdio and Streamable HTTP.

  • Defensive boundaries: Strict schemas, bounded responses, timeouts, retries, safe errors, and loopback-first HTTP defaults protect each trust boundary.

Related MCP server: Histórico Veicular Nacional

Architecture

MCP client
   │
   ├── stdio
   └── Streamable HTTP  http://127.0.0.1:8080/mcp
   │
   ▼
Vehicle Intelligence MCP Server
   ├── strict tool-input validation
   ├── evidence-preserving result projection
   ├── stable error translation
   └── typed asynchronous pipeline client
   │
   ▼  HTTP /v1
NZ Vehicle Data Pipeline API
   ├── canonical records
   ├── reconciliation and confidence
   ├── immutable revisions
   └── source observations

The MCP server has no database and no application cache. All vehicle-data reads pass through one typed asynchronous HTTP client.

Quick start

Prerequisites

  • Git

  • Python 3.12

  • uv 0.5.26 or later

  • Docker with Docker Compose

  • curl

Run the verified demonstration

The smoke script starts both services, seeds deterministic scenarios, exercises both MCP transports, and removes its containers when complete.

mkdir vehicle-intelligence-demo
cd vehicle-intelligence-demo

git clone https://github.com/sovorn-c/nz-vehicle-data-pipeline.git
git -C nz-vehicle-data-pipeline checkout ea49e71075118d6cdc3ed2426cb3620f69792cf6

git clone https://github.com/sovorn-c/vehicle-mcp-server.git
cd vehicle-mcp-server
uv sync --frozen

PIPELINE_DIR="../nz-vehicle-data-pipeline" bash scripts/smoke-local.sh

A successful run demonstrates:

  • catalog discovery from five seeded vehicles

  • clean, risky, unknown, and conflicting evidence states

  • immutable revision history

  • exact source-observation retrieval

  • identical stdio and Streamable HTTP outcomes

Run the server

The upstream pipeline API must be available before the MCP server starts. Its default address is http://localhost:8000.

Start the upstream pipeline (manual testing)

If you are running the MCP server directly or interactively, start and seed the upstream NZ Vehicle Data Pipeline first:

cd /path/to/nz-vehicle-data-pipeline
docker compose up -d --build api
docker compose --profile tools run --rm seed
docker compose --profile tools run --rm seed python -m nz_vehicle_data_pipeline.cli.seed --manifest fixtures/manifest.json --phase2

Verify backend readiness:

curl -s http://localhost:8000/ready
# Output: {"status":"ready","database":"connected"}

stdio

VEHICLE_MCP_PIPELINE_BASE_URL="http://localhost:8000" \
uv run vehicle-mcp-server

Standard output is reserved for MCP protocol messages. Server diagnostics use standard error.

Streamable HTTP

VEHICLE_MCP_TRANSPORT="http" \
VEHICLE_MCP_HTTP_HOST="127.0.0.1" \
VEHICLE_MCP_HTTP_PORT="8080" \
VEHICLE_MCP_PIPELINE_BASE_URL="http://localhost:8000" \
uv run vehicle-mcp-server

The MCP endpoint is http://127.0.0.1:8080/mcp.

Docker Compose

PIPELINE_BASE_URL="http://host.docker.internal:8000" \
docker compose up -d --build

Docker Compose publishes the MCP endpoint on loopback at 127.0.0.1:8080.

Connect an MCP client

The server is model- and client-agnostic. Any MCP client that supports stdio or Streamable HTTP can use the same six tools.

Public ready-to-test demo

A hosted Streamable HTTP endpoint is available for a quick evaluation without running the services locally:

https://vehicle-mcp.chhlatbot.com/mcp

Verified live on 2026-09-01. Add it to the Codex CLI:

codex mcp add vehicle-intelligence-public \
  --url https://vehicle-mcp.chhlatbot.com/mcp

Start Codex, run /mcp to confirm vehicle-intelligence-public is connected, then try:

Use vehicle-intelligence-public to list the available vehicles. Report their makes and total count.

The hosted endpoint contains synthetic demonstration data only and has no uptime SLA. If it is unavailable, use the local stdio setup below, which remains the primary supported setup.

OpenAI Codex (local stdio)

Register the stdio server with the Codex CLI. Replace /path/to/vehicle-mcp-server with the local repository path.

codex mcp add vehicle-intelligence \
  --env VEHICLE_MCP_TRANSPORT=stdio \
  --env VEHICLE_MCP_PIPELINE_BASE_URL=http://localhost:8000 \
  -- uv run --directory /path/to/vehicle-mcp-server vehicle-mcp-server

Verify the shared Codex CLI and IDE-extension configuration:

codex mcp list

See the official Codex MCP configuration guide for UI and config.toml alternatives.

Claude Desktop

Add this entry to claude_desktop_config.json. Replace /path/to/vehicle-mcp-server with the local repository path.

{
  "mcpServers": {
    "vehicle-intelligence": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/vehicle-mcp-server",
        "vehicle-mcp-server"
      ],
      "env": {
        "VEHICLE_MCP_TRANSPORT": "stdio",
        "VEHICLE_MCP_PIPELINE_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

MCP Inspector

Test and inspect tool schemas and queries interactively in your browser with the official MCP Inspector:

# stdio transport (spawns the server as a subprocess)
npx @modelcontextprotocol/inspector uv run vehicle-mcp-server

# Streamable HTTP transport (start the HTTP server first)
npx @modelcontextprotocol/inspector http://127.0.0.1:8080/mcp

Other MCP clients

Use these connection values in clients that provide their own MCP configuration interface:

Transport

Connection

stdio

Command: uv; arguments: run --directory /path/to/vehicle-mcp-server vehicle-mcp-server; set the two environment variables shown above.

Streamable HTTP

URL: http://127.0.0.1:8080/mcp; start the server in HTTP mode first.

Tool catalog

Tool

Main input

Purpose

list_vehicles

limit, offset

Return one bounded page of canonical vehicle summaries for discovery.

lookup_vehicle

vin

Return the current canonical record with provenance, conflicts, confidence, and revision metadata.

explain_vehicle_field

vin, field_name

Explain whether one field is RESOLVED, UNRESOLVED, or ABSENT.

get_vehicle_history

vin, pagination

Return bounded revision history in newest-first order.

get_vehicle_revision

vin, revision_number

Return one exact immutable canonical revision.

get_source_observation

observation_id

Return one exact source observation and its verified raw payload.

Catalog pagination accepts limit values from 1 through 100 and an offset of zero or more. An offset beyond the catalog returns an empty page, not an error.

Discovery-to-audit workflow

  1. Call list_vehicles to discover available records and identify conflicts or later revisions.

  2. Call lookup_vehicle to inspect the current canonical state and its audit metadata.

  3. Call explain_vehicle_field to inspect a resolved, unresolved, or absent field.

  4. Call get_vehicle_history and get_vehicle_revision to compare point-in-time states.

  5. Call get_source_observation with a provenance identifier to inspect the original evidence.

This workflow moves from a bounded summary to raw evidence without placing full payloads in every result.

Engineering decisions

Decision

Reason

Keep reconciliation in the pipeline

One system owns candidate selection, confidence, conflicts, and revision publication.

Use one typed pipeline client

All upstream reads share validation, timeout, retry, response-size, and error rules.

Validate both inputs and responses

The MCP boundary rejects invalid calls and fails closed on upstream contract drift.

Preserve uncertain states

The integration layer does not turn incomplete evidence into a definitive claim.

Keep tools transport-independent

stdio and Streamable HTTP expose the same schemas and behavior.

Avoid local persistence

The server cannot return a silent stale fallback when the pipeline is unavailable.

Security and limitations

  • The server never connects directly to the pipeline database.

  • VINs, observation identifiers, tool arguments, and pipeline responses are treated as untrusted input.

  • Pipeline responses have a configurable size ceiling. Transient idempotent reads use bounded retries.

  • Raw exceptions, stack traces, credentials, and upstream payload values do not enter public errors or diagnostics.

  • Streamable HTTP enables DNS-rebinding protection with loopback Host and Origin allowlists.

  • Non-loopback binding requires the explicit VEHICLE_MCP_ALLOW_INSECURE_BIND=true override.

  • Raw source payloads are available only through get_source_observation.

  • Synthetic records retain a visible synthetic_notice.

  • The project does not claim live access to NZTA, PPSR, Police, insurer, or other restricted registers.

  • The current HTTP mode is for local or private use. Add authentication, authorization, and rate limiting before public deployment.

Configuration

Environment variable

Default

Purpose

VEHICLE_MCP_PIPELINE_BASE_URL

http://localhost:8000

Pipeline API base URL. PIPELINE_BASE_URL is also accepted.

VEHICLE_MCP_TRANSPORT

stdio

Select stdio or http.

VEHICLE_MCP_HTTP_HOST

127.0.0.1

Streamable HTTP bind host.

VEHICLE_MCP_HTTP_PORT

8080

Streamable HTTP bind port.

VEHICLE_MCP_ALLOW_INSECURE_BIND

false

Permit a non-loopback bind for a controlled container network.

VEHICLE_MCP_CONNECT_TIMEOUT

2.0

Pipeline connection timeout in seconds.

VEHICLE_MCP_POOL_TIMEOUT

2.0

Connection-pool timeout in seconds.

VEHICLE_MCP_READ_TIMEOUT

10.0

Pipeline read timeout in seconds.

VEHICLE_MCP_WRITE_TIMEOUT

5.0

Pipeline write timeout in seconds.

VEHICLE_MCP_MAX_ATTEMPTS

3

Maximum attempts for transient reads. Valid range: 1 through 5.

VEHICLE_MCP_MAX_RESPONSE_BYTES

1048576

Maximum pipeline response size. Valid range: 10 KiB through 10 MiB.

Project layout

src/vehicle_mcp_server/
├── client.py       # typed asynchronous pipeline boundary
├── config.py       # immutable environment configuration
├── models.py       # strict tool and upstream contracts
├── server.py       # MCP catalog and transport application
└── tools.py        # tool behavior and safe error translation

tests/
├── acceptance/     # public documentation and delivery contracts
├── integration/    # live pipeline contract checks
└── test_*.py       # unit, transport, security, and parity tests

Verification

Run the complete local preflight:

bash scripts/check.sh

The preflight runs Ruff, formatting checks, strict mypy, pytest, a package build, and a Docker build.

Individual developer checks

Check

Command

Test suite (unit, contract, mock integration)

uv run pytest

Strict type checking

uv run mypy src

Linting

uv run ruff check .

Format verification

uv run ruff format --check .

Package build

uv build

Container build

docker build -t vehicle-mcp-server:local-check .

Standalone demonstration client

With the upstream pipeline running at http://localhost:8000 (and optionally the MCP HTTP server on http://127.0.0.1:8080):

uv run python -m vehicle_mcp_server.demo

Run the cross-repository behavior check:

PIPELINE_DIR="../nz-vehicle-data-pipeline" bash scripts/smoke-local.sh

The CI workflow repeats the preflight stages and runs the smoke check against the pinned compatible pipeline revision.

Project status

Release 0.3.0 provides six read-only tools over stdio and Streamable HTTP with hardened public deployment and edge rate-limiting contracts.

Available Tools

6 tools
explain_vehicle_fieldB

Explain one vehicle field outcome (RESOLVED, UNRESOLVED, or ABSENT) using current evidence.

ParametersJSON Schema
NameRequiredDescriptionDefault
vinYes
field_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
vinYesCanonical 17-character VIN
valueNoResolved canonical value if present
outcomeYesRESOLVED, UNRESOLVED, or ABSENT outcome
conflictsNoRecorded field conflicts if any
rationaleNoHuman-readable explanation of outcome or conflict rationale
field_nameYesEvaluated field name
provenanceNoLineage to supporting source observations
confidence_bandNoOverall revision confidence band
revision_numberYesCanonical revision number evaluated
available_fieldsNoSorted available canonical and conflicting field names
confidence_scoreNoOverall revision confidence score
field_componentsNoPer-field confidence score component breakdown
synthetic_noticeNoDisclaimer notice when record contains synthetic demonstration data
field_confidence_scoreNoPer-field confidence score if evaluated

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of behavioral disclosure. It adds useful context by specifying 'current evidence' and 'explain' implies a read-only operation, but it does not state side effects, permissions, or expected output characteristics. The output schema may compensate slightly, but the description alone is incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It states the action, the resource, and the outcome set immediately, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with an output schema, the description is mostly complete. It clearly identifies the tool's purpose, but the lack of valid field_name values and the absence of guidance on when to prefer this over sibling tools leave minor gaps. Overall, an agent could likely invoke the tool correctly with minimal extra inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema's sparse parameter documentation. It indirectly references field_name via 'vehicle field outcome' but does not explain what field_name values are valid, what vin means beyond its obvious name, or how the two parameters interact. The description adds minimal parameter-level meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Explain') and resource ('one vehicle field outcome'), and enumerates the possible outcomes (RESOLVED, UNRESOLVED, ABSENT), which gives clear scope. It is distinguishable from sibling tools like get_vehicle_history or lookup_vehicle, though it does not explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for explaining a single field's outcome using evidence, and sibling names provide nearby alternatives, but there is no explicit when-to-use or when-not-to-use guidance. An agent can infer the intended use, but must reason about alternatives itself.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_source_observationA

Retrieve one exact immutable source observation by ID, including verified raw payload.

ParametersJSON Schema
NameRequiredDescriptionDefault
observation_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
syntheticYesFlag indicating if observation contains demonstration data
raw_payloadYesExact raw payload string captured from source
retrieved_atYesTimestamp when source evidence was retrieved
source_systemYesSource system name
observation_idYesUnique observation identifier
ingestion_run_idYesIngestion run identifier
source_record_idYesSource-native record identifier
payload_hash_sha256YesSHA-256 fingerprint of the raw payload

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It adds useful behavioral context: the observation is immutable, the retrieval is exact, and the response includes the verified raw payload. It does not explicitly state read-only, but the verb 'Retrieve' makes that clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. It communicates the action, the exactness, the immutability, and the payload content efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter lookup with an output schema, the description covers the core semantics adequately. It lacks guidance on when this tool should be chosen over sibling tools, which prevents a perfect score, but nothing critical is missing for invoking it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only a parameter name and no description (0% coverage), so the description must compensate. The phrase 'by ID' tells the agent that observation_id is the identifier, but it provides no format, origin, or additional constraints beyond the schema's required flag.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description is specific: 'Retrieve one exact immutable source observation by ID' names the verb, the resource, and the lookup key, and adds 'including verified raw payload' to clarify what is returned. It does not explicitly differentiate from sibling tools like get_vehicle_revision, but the resource is distinct enough to be clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for retrieving a single known observation by its ID, but it never states when to prefer it over siblings such as get_vehicle_history or get_vehicle_revision, nor does it mention any exclusions or alternative conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_vehicle_historyB

Retrieve historical canonical revisions for a vehicle in newest-first order.

ParametersJSON Schema
NameRequiredDescriptionDefault
vinYes
limitNo
before_revisionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description partially carries the behavioral burden by disclosing newest-first ordering and that only canonical revisions are returned. It does not mention pagination behavior, whether it is read-only, or how revisions relate to other vehicle data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that conveys the action, object, and ordering without filler. It earns its place and is easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The core operation is clear, but the definition is incomplete for correct invocation because it omits how limit and before_revision should be used. The output schema helps with return values, but not with parameter semantics or pagination strategy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description adds no parameter information. 'vin' and 'limit' are somewhat self-explanatory, but 'before_revision' lacks crucial semantics such as whether it is a cursor, whether it is inclusive, or what revision identifier it expects.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: retrieve historical canonical revisions, and adds a meaningful ordering detail (newest-first). The word 'historical' and the plural 'revisions' distinguish it from the sibling get_vehicle_revision.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus get_vehicle_revision, get_source_observation, or lookup_vehicle. The context is only implied by the phrase 'historical canonical revisions', not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_vehicle_revisionA

Retrieve one exact immutable canonical revision for a vehicle by revision number.

ParametersJSON Schema
NameRequiredDescriptionDefault
vinYes
revision_numberYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
vinYesCanonical 17-character VIN
as_ofYesEvaluation timestamp
conflictsNoRecorded field conflicts
confidenceYesConfidence assessment
revision_idYesUnique revision identifier
published_atYesDatabase publication timestamp
material_hashYesSHA-256 fingerprint of canonical material
revision_numberYesMonotonic revision number
canonical_fieldsYesResolved canonical fields
field_provenanceYesLineage to all supporting source observations
synthetic_noticeNoDisclaimer notice when record contains synthetic demonstration data

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It meaningfully discloses that the revision is immutable, canonical, and singular, which is valuable context beyond the operation name. It does not mention behavior for missing revisions or authentication, but for a simple read-by-revision getter the core behavior is clearly conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence with no filler. It front-loads the action and resource and includes meaningful qualifiers ('exact,' 'immutable,' 'canonical') that clarify behavior without adding length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a low-complexity tool with two scalar required parameters and an output schema present, so the definition does not need to explain return shape. The description adequately captures the core semantics of retrieving a single canonical immutable revision. It would be slightly stronger with explicit guidance on how to know the revision_number or what happens if the revision does not exist.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only elaborates 'revision number' and does not explain that the vehicle is identified by 'vin' or clarify the exact expected semantics of revision_number (e.g., uniqueness, ordering, or range). The parameter names are self-explanatory, but the description adds little meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Retrieve'), names the exact resource ('canonical revision for a vehicle'), and adds the qualifiers 'one exact immutable,' which clearly differentiates this tool from siblings like get_vehicle_history or list_vehicles. An agent can understand the tool's purpose without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when the caller has a specific revision_number and needs the exact canonical revision, but it does not explicitly state when to prefer sibling tools such as get_vehicle_history or when not to use this tool. The usage context is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_vehiclesB

List a bounded page of canonical vehicle summaries from the catalog for discovery.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
offsetNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
itemsYesList of vehicle summaries
limitYesPage size limit
totalYesTotal canonical vehicles matching query
offsetYesPage offset
disclaimerNoSynthetic data limitation notice

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral disclosure burden. It adds useful traits like 'bounded page' and 'canonical' summaries, implying a read-only, paged listing of normalized data. It does not state side effects, ordering, error behavior, or pagination details, but the read-only nature is reasonably inferable from 'List'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, tightly worded sentence with no filler. It front-loads the action and resource, and every phrase contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with two optional parameters and an output schema, so core invocation details are mostly covered. Missing context includes how this listing relates to sibling tools like lookup_vehicle and whether any pagination defaults or ordering behavior are important. It is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explicitly explain how limit and offset control the 'bounded page.' The parameter names and defaults communicate some meaning, but the description fails to compensate for the lack of schema-level documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and identifies the resource ('canonical vehicle summaries from the catalog'), clearly indicating the tool returns a paged collection of summary data. It does not explicitly differentiate itself from siblings like lookup_vehicle, though 'bounded page' suggests a listing operation rather than a single lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'for discovery' implies this tool is meant for browsing or exploring the catalog, which gives some usage context. However, there is no explicit statement about when to use this tool versus lookup_vehicle or any other sibling, and no exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookup_vehicleA

Retrieve the current canonical record and audit metadata for one validated VIN.

ParametersJSON Schema
NameRequiredDescriptionDefault
vinYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
vinYesCanonical 17-character VIN
as_ofYesEvaluation timestamp
conflictsNoRecorded field conflicts
confidenceYesConfidence assessment
revision_idYesUnique revision identifier
published_atYesDatabase publication timestamp
material_hashYesSHA-256 fingerprint of canonical material
revision_numberYesMonotonic revision number
canonical_fieldsYesResolved canonical fields
field_provenanceYesLineage to all supporting source observations
synthetic_noticeNoDisclaimer notice when record contains synthetic demonstration data

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It makes the read-only nature clear through 'Retrieve' and specifies the response concept (canonical record plus audit metadata), but it does not disclose behavior for missing/invalid VINs, the nature of audit metadata, or any validation effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one focused sentence with no filler. It front-loads the action and object and avoids repeating schema information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with an output schema, the description covers the essential purpose and return concept. It does not cover error cases or alternative selection, but those gaps are relatively minor given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add parameter meaning. It contributes 'validated' to the VIN parameter and clarifies it identifies a single vehicle, but it does not provide format, length, or validation requirements. The parameter name is self-explanatory enough to reach the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Retrieve'), a specific resource ('current canonical record'), and a scope ('one validated VIN'). It clearly differentiates from siblings like get_vehicle_history and get_vehicle_revision by emphasizing current canonical state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'current canonical record' implies this tool is for the latest authoritative state rather than history or source observations, but it never explicitly states when to use this tool over alternatives such as get_vehicle_history, get_vehicle_revision, or list_vehicles. Usage guidance is only implied by the wording.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation4/5

Each tool has a distinct role: browsing, current lookup, revision history, exact revision, raw observation, and field explanation. The closest pair is lookup_vehicle and get_vehicle_revision, but their current-vs-immutable distinction is clear from descriptions.

Naming Consistency4/5

Names follow a mostly consistent verb_noun snake_case pattern with list_* for collections and get_* for individual records. lookup_vehicle breaks the get_* convention slightly, but it is still readable and predictable.

Tool Count5/5

Six tools is well within the ideal range and each tool addresses a distinct part of vehicle intelligence. The set feels neither thin nor bloated.

Completeness4/5

The read-only workflow is well covered: discover vehicles, retrieve current and historical canonical states, fetch raw evidence, and explain field outcomes. A minor gap is the lack of a way to enumerate source observations for a vehicle directly rather than by known observation ID.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • used-parts-mcp

    neko-no-otoko
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables searching current used car, truck, and motorcycle parts in the US, resolving vehicles via VIN, and retrieving part listings with source attribution, through read-only MCP tools.
    Apache 2.0

  • ECRVSP Documentos: Impressão

    mcp-dir
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides a read-only tool to query official vehicle documentation for printing low vehicle certificates, with pay-per-use prepaid credits and no platform credentials required.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sovorn-c/vehicle-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server