# Better Vetters MCP server

A stdio MCP server that exposes two tools, `check_contractor` and `get_coverage`, by calling the Better Vetters HTTP API. Billing for checks uses your API key.

Download the stdio server: https://api.bettervetters.com/mcp/server.py

## Remote (streamable HTTP)

The same tools are also served as a hosted MCP endpoint:

- URL: `https://api.bettervetters.com/mcp`
- Transport: streamable HTTP
- Auth: `Authorization: Bearer <api key>` (or `X-API-Key`). Required for `check_contractor`. `get_coverage` is free and works without a key.
- Error messages are JSON: `missing_api_key` or `invalid_api_key` if the key is missing or wrong.

Example client config (Claude, Cursor, and other streamable-HTTP clients):

```json
{
  "mcpServers": {
    "better-vetters": {
      "url": "https://api.bettervetters.com/mcp",
      "headers": {
        "Authorization": "Bearer bv_live_YOUR_KEY"
      }
    }
  }
}
```

The stdio server below is the local alternative if you prefer to run a process yourself.


## Setup

1. Create an API key: `POST https://api.bettervetters.com/v1/keys` with body `{"label":"mcp"}`. Store the `bv_live_...` key; it is shown once.
2. Save `server.py` somewhere local and install its Python dependencies: `pip install mcp httpx`
3. Add this to your MCP client config (Claude Desktop, Cursor, and most other stdio clients):

```json
{
  "mcpServers": {
    "better-vetters": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "CONTRACTOR_CHECK_API_URL": "https://api.bettervetters.com",
        "CONTRACTOR_CHECK_API_KEY": "bv_live_YOUR_KEY"
      }
    }
  }
}
```

Replace `/path/to/server.py` with the real path and `bv_live_YOUR_KEY` with your key.

Environment variables (existing names are unchanged; aliases are accepted):

- `CONTRACTOR_CHECK_API_URL` (alias: `BETTER_VETTERS_API_URL`) — default `http://localhost:8080`
- `CONTRACTOR_CHECK_API_KEY` (alias: `BETTER_VETTERS_API_KEY`) — required for `check_contractor`

Existing `cc_live_` keys continue to work. New keys use the `bv_live_` prefix.

## Tools

- `check_contractor` — billed per call (default $0.15). Inputs: name (required), state, city, license_number, phone, website.
- `get_coverage` — free. Lists jurisdictions, sources, record counts, and freshness.

## Notes

Public records only; not a consumer report or legal advice. Treat `match.confidence` below 0.8 as a possible match.

Better Vetters is operated by James Russell, a sole proprietor based in Waterford, PA. Contact: james@fullyarmedmarketing.com. Site: https://bettervetters.com.