MCP (Model Context Protocol)

Connect AI assistants like Claude directly to GovData. Ask questions about UK tax, companies, and bank holidays in natural language.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants call external tools, read data, and use prompt templates. GovData implements an MCP server so AI assistants can query UK Government data natively — no code required.

Instead of writing API calls, you can ask Claude or any MCP-compatible assistant questions like "What's my take-home pay on a 55k salary in Scotland?" or "Look up company number 00000006" and it will call the right GovData tools automatically.

Connection details

URL	`https://mcp.govdata.dev/mcp`
Transport	Streamable HTTP
Authentication	Bearer token — same API key as the REST API
Mode	Stateless (no session required)

Setup guides

Before you start

Create a GovData account (free)
Copy your API key from the console dashboard
Your key starts with gd_live_ (production) or gd_test_ (testing) — both work with MCP

Claude Desktop

Claude Desktop has built-in MCP support.

Step 1: Open the config file

Open Claude Desktop, go to Settings (gear icon) → Developer → Edit Config. This opens claude_desktop_config.json.

Or open it directly: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 2: Add the GovData server

Add the following to your config file. If the file already has other MCP servers, add the govdata entry inside the existing mcpServers object.

{
  "mcpServers": {
    "govdata": {
      "url": "https://mcp.govdata.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your actual API key.

Step 3: Restart and verify

Restart Claude Desktop. You should see a hammer icon in the chat input — click it to see the 47 GovData tools available. Try asking:

"What's my take-home pay on a £55,000 salary in Scotland with a Plan 2 student loan?"

Claude Code (CLI)

Claude Code supports remote MCP servers. Add GovData to your project or global config.

Option A: Add to a project

Run this in your project directory:

claude mcp add govdata \\
  --transport http \\
  "https://mcp.govdata.dev/mcp" \\
  --header "Authorization: Bearer YOUR_API_KEY"

Option B: Add globally

Available in all projects:

claude mcp add govdata \\
  --transport http \\
  --scope user \\
  "https://mcp.govdata.dev/mcp" \\
  --header "Authorization: Bearer YOUR_API_KEY"

Verify it works

Start Claude Code and ask a question:

claude
> What are the current UK income tax bands for Scotland?

Other MCP clients

Any MCP client that supports Streamable HTTP transport can connect to GovData. The configuration varies by client, but the core details are the same:

Server URL	`https://mcp.govdata.dev/mcp`
Transport	Streamable HTTP (not stdio)
Auth header	`Authorization: Bearer YOUR_API_KEY`
Content-Type	`application/json`

Generic JSON config

Most MCP clients accept a JSON config like this:

{
  "govdata": {
    "url": "https://mcp.govdata.dev/mcp",
    "transport": "streamable-http",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

Testing with cURL

You can test the MCP endpoint directly:

# List available tools
curl -X POST https://mcp.govdata.dev/mcp \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST https://mcp.govdata.dev/mcp \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"calculate_income_tax","arguments":{"gross_income":55000}}}'

Example conversations

Once connected, just ask questions in plain English. Here are some things you can do:

"What's my take-home pay on a £55,000 salary in Scotland with a Plan 2 student loan and 5% pension?"

Uses calculate_take_home_pay — returns net annual, monthly, and weekly pay with full deduction breakdown.

"Compare the income tax on £80,000 in England vs Scotland for 2025-26."

Uses calculate_income_tax twice — once for each region.

"Look up Tesco PLC and tell me their SIC codes."

Uses search_companies then lookup_company to find and detail the company.

"When's the next bank holiday in Scotland?"

Reads the govdata://calendar/bank-holidays/next resource.

"I sold a buy-to-let property for a £40,000 gain. I'm a higher-rate taxpayer. How much CGT do I owe?"

Uses calculate_capital_gains_tax with residential property rates.

Available tools

Tools perform calculations and lookups. The AI decides when to call them based on your question. Each tool call costs 10 credits.

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n

Tool	Description	Cost
`calculate_income_tax`	Calculate UK income tax for a given gross income and region. Returns a full breakdown by tax band, personal allowance, taxable income, total tax, and effective rate.	10
`calculate_national_insurance`	Calculate UK National Insurance contributions. Supports employed (Class 1) and self-employed (Class 2 and Class 4). Returns contribution breakdowns by band.	10
`lookup_ni_categories`	Look up all UK National Insurance category letters (A, B, C, H, J, M, V, Z, plus Freeport and Investment Zone letters) with descriptions and employee/employer contribution rates for a given tax year.	10
`calculate_take_home_pay`	Calculate UK take-home pay from gross income. Combines income tax, National Insurance, student loan repayments, and pension contributions into a single net pay calculation with full deduction breakdown.	10
`compare_tax`	Compare take-home pay between two scenarios. Takes two sets of inputs (salary, region, student loans, pension) and returns a side-by-side comparison with differences.	10
`calculate_capital_gains_tax`	Calculate UK Capital Gains Tax on a disposal. Accounts for the annual exempt amount. Requires the asset type and the taxpayer's income tax band.	10
`calculate_dividend_tax`	Calculate UK dividend tax. Accounts for the dividend allowance. Requires the taxpayer's income tax band to determine the applicable dividend tax rate.	10
`calculate_corporation_tax`	Calculate UK Corporation Tax on company profits. Handles small profits rate, main rate, and marginal relief for profits between the two thresholds.	10
`calculate_vat`	Calculate UK VAT on an amount. Supports adding VAT to a net amount (exclusive) or extracting VAT from a gross amount (inclusive). Works with standard, reduced, and zero rates.	10
`calculate_student_loan`	Calculate UK student loan repayments based on annual income. Supports Plan 1, Plan 2, Plan 4, Plan 5, and Postgraduate loan types. Multiple plans can be calculated simultaneously.	10
`calculate_vat_return`	Calculate the 9 HMRC VAT Return boxes from a set of transactions. Supports standard VAT, flat rate scheme, partial exemption, fuel scale charges, and more. Provide company details, the return period, and an array of transactions.	10
`calculate_employer_cost`	Calculate the total cost to an employer of hiring staff in the UK. Includes salary, employer National Insurance contributions, and workplace pension. Can calculate for multiple employees.	10
`lookup_company`	Look up a UK company by its Companies House company number. Returns company name, status, type, date of creation, registered office address, and SIC codes.	10
`search_companies`	Search for UK companies by name. Returns matching companies ranked by name similarity. Optionally filter by company status (e.g. 'active', 'dissolved').	10
`company_health_score`	Get a financial health assessment for a UK company. Calculates key ratios (current ratio, debt-to-equity, profit margin, ROA, cash ratio) from the latest filing and rates each as green/amber/red.	10
`company_financial_trends`	Get year-over-year financial trends for a UK company. Returns time series of revenue, profit, assets, and employees across all filed accounts, plus percentage changes between consecutive periods.	10
`sector_analytics`	Get sector-level analytics for a UK SIC code. Returns company counts, active/inactive breakdown, incorporation trends (this year vs last year), and financial benchmarks if available.	10
`company_psc`	Get Persons with Significant Control (PSC) for a UK company. Returns individuals, corporate entities, and legal persons who have significant control over the company, including their natures of control and notification dates.	10
`company_psc_changes`	Get a timeline of PSC (Persons with Significant Control) changes for a UK company — appointments and cessations in chronological order.	10
`company_filing_status`	Check a UK company's filing compliance status. Returns whether accounts are overdue, due soon, or up to date, along with next due dates and latest filing details.	10
`company_network`	Map the ownership network of a UK company. Shows who controls the company (PSCs) and what other companies those same people control. Useful for identifying connected businesses and beneficial ownership chains.	10
`geographic_companies`	Get company statistics for a UK postcode area. Returns company counts, active/inactive breakdown, top industries (SIC codes), and incorporation trends for the given postcode prefix (e.g. 'EC2', 'M1', 'EH1').	10
`recent_filings`	Get recently filed company accounts from Companies House. Returns the most recent filings in reverse chronological order. Can filter by filing type, SIC code, or date.	10
`company_timeline`	Get a chronological timeline of key events for a UK company. Includes incorporation, account filings, PSC changes, and cessation events.	10
`lookup_minimum_wage`	Look up UK National Minimum Wage and National Living Wage rates by age band for a given tax year.	10
`lookup_auto_enrolment`	Look up UK workplace pension auto-enrolment thresholds and minimum contribution rates for a given tax year.	10
`lookup_earnings`	Look up ONS ASHE median and mean gross hourly, weekly and annual earnings by region, industry and occupation.	10
`lookup_statutory_payments`	Look up UK statutory payment rates (SSP, SMP, SPP, SAP, ShPP, SPBP, SNCP) for a given tax year.	10
`lookup_child_benefit`	Look up UK Child Benefit rates and High Income Child Benefit Charge thresholds for a given tax year.	10
`lookup_universal_credit`	Look up UK Universal Credit component rates (standard allowances, child elements, disability, carer, childcare, work allowances, taper rate) for a given tax year.	10
`lookup_council_tax`	Look up 2026-27 England council tax amounts by billing authority and valuation band. Amounts are the full area council tax including major, parish, and adult social care precepts: what a two-adult household pays before discounts.	10
`lookup_hpi`	Look up UK House Price Index history by region name or official area code.	10
`search_property_transactions`	Search UK property transactions (HM Land Registry Price Paid Data) by postcode, with optional date range and property type filters.	10
`search_property_address`	Search UK property transaction history for a specific address. Returns all recorded sales from HM Land Registry Price Paid Data with prices, dates, and property details. Ideal for finding the sale history of a specific property.	10
`property_statistics`	Get UK property transaction statistics (average, median, min, max prices and breakdown by type) for a postcode, town, or district.	10
`lookup_inflation`	Look up UK inflation data (CPI, CPIH, or RPI) with the most recent observations. Returns percentage values over time.	10
`lookup_economic_data`	Look up UK economic indicators — GDP growth, unemployment rate, or house price index — with recent observations over time.	10
`lookup_bank_holidays`	Look up UK bank holidays — upcoming holidays, by calendar year, or by region (england_and_wales, scotland, northern_ireland). Hyphenated aliases are also accepted.	10
`search_legislation`	Search UK legislation (Acts of Parliament, Statutory Instruments, etc.) by title keyword, legislation type, and/or year.	10
`lookup_legislation`	Look up a specific piece of UK legislation by its type, year, and number (e.g. ukpga/2006/46 for the Companies Act 2006).	10
`lookup_food_hygiene`	Search UK Food Standards Agency hygiene ratings by business name, postcode, local authority, rating, or business type. Supports numeric FHRS ratings and Scotland's textual FHIS results.	10
`search_crime`	Search paginated Police.uk street-level crime by month, category, force, or LSOA. Locations are approximate anonymised snap-points.	10
`list_crime_categories`	List the distinct Police.uk crime categories currently held by GovData.	10
`lookup_energy_price_cap`	Look up Ofgem energy price-cap unit rates and daily standing charges by cap period, fuel, payment method, and GB region.	10
`lookup_school_inspections`	Look up Ofsted inspection outcomes for state-funded schools in England by URN, name, postcode, local authority, phase, or judgement.	10
`lookup_mot_pass_rates`	Look up pre-aggregated 2025 MOT pass rates by vehicle make, model, fuel type, and vehicle age band.	10
`lookup_mot_failures`	Look up pre-aggregated common 2025 MOT failure, PRS, advisory, and minor reasons by make and model.	10

Available resources

Resources provide read-only reference data. The AI loads them into context when needed. Each resource read costs 1 credit.

Static resources

URI	Description	Cost
`govdata://tax/years/current`	Current active UK tax year with key dates	1
`govdata://tax/years`	All available UK tax years	1
`govdata://tax/vat/rates`	Current UK VAT rates (standard, reduced, zero)	1
`govdata://tax/vat/flat-rate-percentages`	VAT flat rate scheme percentages by business type	1
`govdata://calendar/bank-holidays/next`	Next upcoming UK bank holidays by region	1
`govdata://companies/sic-codes`	UK Standard Industrial Classification codes directory	1
`govdata://companies/statistics`	Platform-wide UK company statistics	1
`govdata://economics/inflation/latest`	Latest UK CPI, CPIH, and RPI inflation rates	1
`govdata://legislation/types`	UK legislation type codes and their descriptions	1

Parameterised resource templates

URI template	Description	Cost
`govdata://tax/income-tax/rates/{tax_year}`	Income tax bands and rates for a given tax year	1
`govdata://tax/national-insurance/thresholds/{tax_year}`	NI thresholds and rates for a given tax year	1
`govdata://tax/capital-gains/rates/{tax_year}`	Capital Gains Tax rates and allowances	1
`govdata://tax/dividends/rates/{tax_year}`	Dividend tax rates and allowances	1
`govdata://tax/corporation/rates/{tax_year}`	Corporation Tax rates	1
`govdata://tax/student-loan/thresholds/{tax_year}`	Student loan repayment thresholds	1
`govdata://tax/pension/allowances/{tax_year}`	Pension annual and lifetime allowances	1
`govdata://calendar/bank-holidays/{year}`	Bank holidays for a specific calendar year	1
`govdata://employment/minimum-wage/{tax_year}`	Minimum wage rates by age band for a given tax year	1
`govdata://employment/auto-enrolment/{tax_year}`	Auto-enrolment thresholds and contribution rates	1
`govdata://benefits/statutory-payments/{tax_year}`	Statutory payment rates (SSP, SMP, SPP, etc.)	1
`govdata://benefits/child-benefit/{tax_year}`	Child Benefit rates for a given tax year	1
`govdata://benefits/universal-credit/{tax_year}`	Universal Credit component rates	1
`govdata://economics/inflation/{metric}`	Inflation time series (cpi, cpih, or rpi)	1
`govdata://economics/indicators/{metric}`	Economic indicator time series (unemployment or hpi)	1

Available prompts

Prompts are pre-built templates that guide the AI to use the right tools and present results clearly. Prompts are free — only the tool calls they trigger cost credits.

Prompt	Description
`tax-summary`	Comprehensive summary of all UK tax rates, bands, and thresholds for a tax year
`take-home-breakdown`	Payslip-style take-home pay breakdown with all deductions from gross to net
`company-report`	Structured company overview from Companies House data
`company-due-diligence`	Comprehensive due diligence: health score, trends, PSC network, filing compliance, risk assessment
`company-comparison`	Side-by-side comparison of two companies: financials, health, filings, and ownership
`employer-cost-breakdown`	Full employer cost analysis: salary, employer NI, pension, and total cost per employee
`property-area-report`	Area-level property analysis: price trends, transaction volumes, and property type breakdown
`benefits-eligibility`	Benefits entitlement check: statutory payments, child benefit, and universal credit eligibility
`contractor-tax-comparison`	Compare tax efficiency of employed vs self-employed vs limited company for the same gross income
`salary-region-comparison`	Compare take-home pay across UK tax regions for the same gross salary
`company-risk-monitor`	Risk monitoring check on a UK company: filing compliance, PSC changes, financial trajectory, health score
`tax-year-comparison`	Compare UK tax rates, bands, and thresholds between two tax years
`property-investment-analysis`	Analyse a UK area for property investment: price trends, yields, CGT implications
`small-business-tax-guide`	Tax obligations overview for a new UK small business
`economic-briefing`	Current UK economic snapshot: inflation, unemployment, and house prices
`legislation-research`	Search and summarise UK legislation relevant to a topic
`dividend-salary-split`	Find the optimal salary/dividend split for a UK company director
`student-loan-impact`	Analyse student loan repayment impact on take-home pay across salary levels
`vat-registration-analysis`	Analyse whether to register for VAT, compare standard vs flat rate schemes
`pension-contribution-analysis`	Analyse impact of different pension contribution rates on take-home pay and tax relief
`sector-deep-dive`	Deep dive into a UK industry sector: company counts, benchmarks, geographic hotspots
`company-ownership-map`	Map ownership structure of a UK company and connected entities
`maternity-paternity-guide`	UK statutory entitlements for new parents: maternity, paternity, shared parental pay
`hiring-budget-planner`	Plan total cost of hiring a team at different salary levels
`area-business-profile`	Business landscape profile for a UK postcode area
`property-price-history`	Detailed transaction history for a UK address or street

Credit costs

MCP uses the same credit system as the REST API:

Tools

10 credits

Calculations and lookups

Resources

1 credit

Reference data reads

Prompts

Free

Only triggered tools cost credits

Troubleshooting

"Invalid API key" or 401 error

Check that your API key is correct and starts with gd_live_ or gd_test_. Make sure the Authorization header includes the Bearer prefix.

"Insufficient credits"

Your credit balance is too low for the request. Tool calls cost 10 credits, resource reads cost 1. Top up in the console or wait for your free credits to reset on the 1st of the month.

Tools not appearing in Claude Desktop

Make sure you've restarted Claude Desktop after editing the config. Check for JSON syntax errors in claude_desktop_config.json (trailing commas, missing quotes). The hammer icon in the chat input should show 47 tools.

Rate limit exceeded (429)

MCP shares rate limits with the REST API. The response includes a Retry-After header. Wait the indicated time before retrying.

What's next

Authentication guide — test vs live keys, key rotation
Rate limits — understand credit usage and limits
Tax API reference — full REST API docs for the same endpoints
Companies API reference — company search and lookup docs