GovData Docs

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

  1. Create a GovData account (free)
  2. Copy your API key from the console dashboard
  3. 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 11 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 streamable-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 streamable-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.

Tool Description Cost
calculate_take_home_pay Full take-home pay: income tax + NI + student loan + pension in one call 10
calculate_income_tax Income tax with band-by-band breakdown for any region 10
calculate_national_insurance Employee or self-employed NI contributions 10
calculate_vat Add or extract VAT at standard, reduced, or zero rate 10
calculate_vat_return Full 9-box VAT return from transactions 10
calculate_capital_gains_tax CGT on disposals with annual exempt amount 10
calculate_dividend_tax Dividend tax with allowance and band-based rates 10
calculate_corporation_tax Corporation tax with marginal relief 10
calculate_student_loan Student loan repayments for Plans 1, 2, 4, 5, and Postgrad 10
lookup_company Look up a UK company by Companies House number 10
search_companies Search UK companies by name with optional status filter 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

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

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

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 11 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