# VATFind MCP
Reviewed: 2026-10-06. Tool definitions below come from the same contract used by tools/list.

Endpoint: https://vatfind.com/api/mcp
Transport: stateless Streamable HTTP
Protocol versions: 2026-07-28, 2025-11-25
Authentication: OAuth authorization code with PKCE S256
Protected resource: https://vatfind.com/.well-known/oauth-protected-resource/api/mcp
Authorization server: https://vatfind.com/.well-known/oauth-authorization-server
Human reference: https://vatfind.com/docs/mcp
Machine tool catalogue: https://vatfind.com/docs/mcp/tools.json
Registry publication metadata: https://vatfind.com/server.json

## Connect and complete a company lookup
1. Add the exact endpoint to a client that supports remote MCP and OAuth.
2. Sign in to VATFind and approve the scopes needed for the chosen workflow.
3. Call get_country_capabilities with country_code to inspect supported evidence dimensions.
4. Call find_vat_number with company_name, country_code and a stable idempotency_key.
5. Compare the candidates with supplier documents. Ask for clarification when the legal entity is ambiguous.
6. If a number is supplied, call check_vat_number or check_tax_identifier with a new operation-specific idempotency_key.
7. Report each returned status, source, timestamp and warning independently. Leave approval decisions to customer policy.

## Costs and permissions
MCP uses live workspace processing. Billable calls require paid access and consume the same check allowance as REST. Get coverage, usage, stored checks and monitoring events without a new check charge. Every billable or mutating call needs an idempotency_key. A monitor creates a billable baseline; each successful refresh uses a check. Obtain explicit user confirmation before creating, changing or archiving monitoring. Reconnect to obtain additional scopes; refresh tokens cannot silently add permissions.

## Tools
### check_vat_number
Scope: checks:run
Checks syntax and exact company-registry association for a VAT number. Read each returned status independently. Never claim a VAT registration is active unless tax_authority_status explicitly says valid; not_checked is not valid.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "vat_number",
    "country_code",
    "idempotency_key"
  ],
  "properties": {
    "vat_number": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "country_code": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "company_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{8,128}$",
      "description": "Stable retry key retained for 24 hours."
    }
  }
}
```

### find_vat_number
Scope: companies:search
Searches company records by company name or registration number and returns candidates. Do not silently choose a candidate when more than one is returned.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "country_code",
    "idempotency_key"
  ],
  "anyOf": [
    {
      "required": [
        "company_name"
      ]
    },
    {
      "required": [
        "registration_number"
      ]
    }
  ],
  "properties": {
    "country_code": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "company_name": {
      "type": "string",
      "minLength": 2,
      "maxLength": 256
    },
    "registration_number": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "city_or_state": {
      "type": "array",
      "maxItems": 10,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "pattern": "\\S"
      }
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{8,128}$",
      "description": "Stable retry key retained for 24 hours."
    }
  }
}
```

### check_tax_identifier
Scope: checks:run
Checks the syntax and exact company-record association of a non-VAT tax identifier. It does not imply a live tax-authority validation.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "tax_identifier",
    "country_code",
    "idempotency_key"
  ],
  "properties": {
    "tax_identifier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "country_code": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "company_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{8,128}$",
      "description": "Stable retry key retained for 24 hours."
    }
  }
}
```

### get_check
Scope: checks:read
Retrieves a prior VATFind check by its opaque check ID for the authenticated workspace.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "check_id"
  ],
  "properties": {
    "check_id": {
      "type": "string",
      "pattern": "^chk_[A-Za-z0-9_-]{16,80}$"
    }
  }
}
```

### get_country_capabilities
Scope: coverage:read
Returns supported identifier types, format hints, registry matching, tax-authority checking, and company-status coverage for one country.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "country_code"
  ],
  "properties": {
    "country_code": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    }
  }
}
```

### get_usage
Scope: usage:read
Returns this workspace's current-period recorded operation counts, billable units, and remaining allowance across REST, MCP, monitoring, and workspace channels. Counts represent completed usage events, not every HTTP attempt.

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {}
}
```

### create_vat_monitor
Scope: monitoring:write
Creates a baseline and schedules recurring company-record checks for a VAT number. The legacy tool name is retained for compatibility; it does not monitor authority-reported VAT status. Each successful baseline or refresh consumes one check. Configure signed webhooks through the REST API or dashboard.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "vat_number",
    "country_code",
    "cadence",
    "idempotency_key"
  ],
  "properties": {
    "vat_number": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "country_code": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "cadence": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly"
      ]
    },
    "company_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "client_reference": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "watched_fields": {
      "type": "array",
      "minItems": 1,
      "maxItems": 6,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "registry_match_status",
          "company_legal_status",
          "legal_name",
          "registration_number",
          "vat_numbers",
          "registered_address"
        ]
      }
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{8,128}$",
      "description": "Stable retry key retained for 24 hours."
    }
  }
}
```

### list_vat_monitors
Scope: monitoring:read
Lists company-record monitors in the authenticated workspace and environment.

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    }
  }
}
```

### get_vat_monitor
Scope: monitoring:read
Retrieves one company-record monitor, its latest successful company-record snapshot, health, and next target check time.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "monitor_id"
  ],
  "properties": {
    "monitor_id": {
      "type": "string",
      "pattern": "^mon_[A-Za-z0-9_-]{16,80}$"
    }
  }
}
```

### update_vat_monitor
Scope: monitoring:write
Pauses or resumes a company-record monitor and changes its cadence or watched company-record fields.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "monitor_id",
    "idempotency_key"
  ],
  "anyOf": [
    {
      "required": [
        "status"
      ]
    },
    {
      "required": [
        "cadence"
      ]
    },
    {
      "required": [
        "watched_fields"
      ]
    }
  ],
  "properties": {
    "monitor_id": {
      "type": "string",
      "pattern": "^mon_[A-Za-z0-9_-]{16,80}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused"
      ]
    },
    "cadence": {
      "type": "string",
      "enum": [
        "daily",
        "weekly",
        "monthly"
      ]
    },
    "watched_fields": {
      "type": "array",
      "minItems": 1,
      "maxItems": 6,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "enum": [
          "registry_match_status",
          "company_legal_status",
          "legal_name",
          "registration_number",
          "vat_numbers",
          "registered_address"
        ]
      }
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{8,128}$",
      "description": "Stable retry key retained for 24 hours."
    }
  }
}
```

### run_vat_monitor
Scope: monitoring:write
Runs an on-demand refresh for a company-record monitor. A successful refresh consumes one check.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "monitor_id",
    "idempotency_key"
  ],
  "properties": {
    "monitor_id": {
      "type": "string",
      "pattern": "^mon_[A-Za-z0-9_-]{16,80}$"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{8,128}$",
      "description": "Stable retry key retained for 24 hours."
    }
  }
}
```

### archive_vat_monitor
Scope: monitoring:write
Stops future checks and archives a company-record monitor while retaining its event evidence.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "monitor_id",
    "idempotency_key"
  ],
  "properties": {
    "monitor_id": {
      "type": "string",
      "pattern": "^mon_[A-Za-z0-9_-]{16,80}$"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9._-]{8,128}$",
      "description": "Stable retry key retained for 24 hours."
    }
  }
}
```

### list_vat_monitor_events
Scope: monitoring:events
Lists material company-record changes and operational monitoring events for the authenticated workspace.

```json
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "monitor_id": {
      "type": "string",
      "pattern": "^mon_[A-Za-z0-9_-]{16,80}$"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024
    }
  }
}
```

### get_vat_monitor_event
Scope: monitoring:events
Retrieves one monitoring event with its canonical field changes and delivery state.

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "event_id"
  ],
  "properties": {
    "event_id": {
      "type": "string",
      "pattern": "^evt_[A-Za-z0-9_-]{16,80}$"
    }
  }
}
```

## Current commercial and coverage information
- Pricing: https://vatfind.com/pricing
- Country capabilities: https://vatfind.com/coverage
- Data and result boundaries: https://vatfind.com/data
- Service and licensing terms: https://vatfind.com/terms
- Security: https://vatfind.com/security
- Enterprise and bulk requirements: https://vatfind.com/contact

Field availability varies by country and source. A retrieval timestamp is not the registry's last-update timestamp. Keep format, company-record association, company legal status and tax-authority status separate. A missing field is not a negative check. Current REST checks do not call a live tax-authority service.