MODEL CONTEXT PROTOCOL
VATFind MCP.
Company facts for agents.
Give an MCP-compatible client a small, typed set of VATFind tools without copying API keys into prompts or configuration files.
https://vatfind.com/api/mcpAdd this URL as a custom MCP server. Your client discovers VATFind OAuth, opens the VATFind sign-in and consent screen, and receives a short-lived token scoped to your workspace.
Follow the agent quickstart, or read the Markdown reference and tool schemas.
In ChatGPT, enable Developer mode, create a custom MCP connection, and paste the endpoint above. In Claude or another compatible client, create a remote HTTP MCP server with the same URL and choose OAuth when prompted. Exact menu labels vary by client version.
OAuth and permissions
VATFind uses authorization code flow with PKCE S256 and resource-bound bearer tokens. The authorization issuer is https://vatfind.com; the protected resource is exactly https://vatfind.com/api/mcp. Clients can discover metadata from the standard well-known URLs.
Protected resource metadata
https://vatfind.com/.well-known/oauth-protected-resource/api/mcp
Authorization server metadata
https://vatfind.com/.well-known/oauth-authorization-serverVATFind uses public-client dynamic registration. Redirect URLs must use HTTPS, except HTTP loopback URLs for native clients. The consent screen shows the registered client ID and redirect host before approval. Access tokens expire after one hour, refresh tokens rotate automatically, and every invocation is checked against the requested resource and scopes. MCP currently runs against live processing; use REST with a vf_test_… key for deterministic sandbox fixtures.
Tool catalogue
| Tool | OAuth scope | Purpose |
|---|---|---|
check_vat_number | 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. |
find_vat_number | 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. |
check_tax_identifier | 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. |
get_check | checks:read | Retrieves a prior VATFind check by its opaque check ID for the authenticated workspace. |
get_country_capabilities | coverage:read | Returns supported identifier types, format hints, registry matching, tax-authority checking, and company-status coverage for one country. |
get_usage | 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. |
create_vat_monitor | 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. |
list_vat_monitors | monitoring:read | Lists company-record monitors in the authenticated workspace and environment. |
get_vat_monitor | monitoring:read | Retrieves one company-record monitor, its latest successful company-record snapshot, health, and next target check time. |
update_vat_monitor | monitoring:write | Pauses or resumes a company-record monitor and changes its cadence or watched company-record fields. |
run_vat_monitor | monitoring:write | Runs an on-demand refresh for a company-record monitor. A successful refresh consumes one check. |
archive_vat_monitor | monitoring:write | Stops future checks and archives a company-record monitor while retaining its event evidence. |
list_vat_monitor_events | monitoring:events | Lists material company-record changes and operational monitoring events for the authenticated workspace. |
get_vat_monitor_event | monitoring:events | Retrieves one monitoring event with its canonical field changes and delivery state. |
Useful prompts include “Check whether GB123456789 is associated with a company record,” “Create a weekly company-record monitor for this supplier,” and “List unreviewed monitoring events.” The legacy tool names retain vat_monitor for API compatibility, but the current monitor contract rechecks company-record fields—not authority-reported VAT-registration status. The client—not VATFind—decides when to call a tool. Existing OAuth connections must reconnect before they can receive the new monitoring scopes; refresh tokens cannot silently add permissions.
Agent-safe result semantics
Check and monitoring tools return the same structured content as REST; archive_vat_monitor also returns the archived monitor_id for agent correlation. They include a concise text summary for clients that do not yet consume structured output.
The server instructs models to keep format_status, registry_match_status, tax_authority_status, and company_legal_status separate. A model must not call a VAT registration active when tax_authority_status is not_supported or not_checked. An active monitor means its schedule is enabled, not that the VAT registration is active.
Billable MCP calls use the same workspace credits and usage ledger as live REST calls. They require active paid access, including the three-day grace period after a failed renewal. When that access pauses, credentials and read-only workspace data remain available, but billable MCP checks and monitoring operations return payment_required until Stripe confirms payment. Creating a monitor establishes a paid baseline; successful scheduled and manual refreshes use one check. Read-only retrieval, coverage, event, and usage tools do not consume a credit. Billable and mutating tools require an idempotency_key; reuse the same value when retrying the same operation within 24 hours.
Protocol and client compatibility
The endpoint uses stateless Streamable HTTP and implements MCP revision 2026-07-28 with per-request metadata, mirrored HTTP headers, server/discover, structured results, and cache hints. It also accepts a validated 2025-11-25 initialization flow for clients still completing the transition. There is no persistent MCP session, standalone GET event stream, or deprecated HTTP+SSE endpoint.
VATFind validates Host and browser Origin headers, orders tools deterministically, validates tool inputs against bounded JSON schemas, and checks tool scopes on every call. Tool invocation is limited to 60 calls per minute per connection and 120 per minute per workspace. MCP uses the same live daily check and monitoring limits and the same 730-day artifact retention described in the REST documentation. Missing or expired credentials return 401 with protected-resource discovery; insufficient scopes return 403 with the scope required for step-up authorization.
COMPANY MONITORING THROUGH MCP
Keep creation, review and action as separate agent steps.
- 01Create the company baseline
Call
create_vat_monitorwith the identifier, country, cadence, watched company fields and an idempotency key. Baseline creation is billable. Reusing the same key and arguments within 24 hours returns the exact completed structured response instead of repeating the mutation. - 02Read structured change events
Use
list_vat_monitor_eventsto find material company changes or source-health events, then retrieve the selected event by ID. - 03Apply customer policy
The tool returns evidence and change states; the client or reviewer decides whether to retry, request documents, pause a workflow or take no action.
Read the monitoring page for watched-field, cadence and evidence boundaries. Read the REST section for signed-webhook delivery. Authority-backed VAT-status monitoring is a separate coverage requirement on the same page.
Troubleshooting connection and tool calls
| Symptom | Check | Next action |
|---|---|---|
| OAuth does not open | Confirm the exact HTTPS endpoint and that the client supports remote OAuth discovery. | Remove stale server configuration, add https://vatfind.com/api/mcp again, and inspect the client's connection log. |
401 response | The token may be missing, expired or issued for another resource. | Reconnect through the client so it discovers the protected resource and obtains a fresh token. |
403 response | The connection lacks the scope required by the selected tool. | Reconnect and approve the required scope; existing refresh tokens cannot silently add it. |
| Tool is not listed | The client may cache the catalogue or hold an older authorization grant. | Refresh or recreate the connection, then compare the discovered catalogue with this page. |
| Result looks incomplete | Optional source fields may be absent and authority status may be unsupported or not checked. | Read the structured status fields and warnings; do not infer a broader conclusion from missing data. |