MCP Server

This calculator exposes a Model Context Protocol (MCP) server, allowing AI assistants like Claude to directly calculate UK benefit eligibility.

What is MCP?

The Model Context Protocol is an open standard that lets AI models discover and use tools, read data, and follow guided workflows. By connecting an MCP client to this server, an AI assistant can guide users through a benefits assessment conversationally.

Endpoint

The MCP server is available at:

https://missingbenefit.com/mcp

Transport: Streamable HTTP (stateless, no session tracking required). Only POST requests are accepted with Content-Type: application/json. Responses use Server-Sent Events (SSE) format.

Available tools

calculate-benefits

Submit questionnaire answers and receive detailed benefit eligibility calculations for the 2025/26 tax year. Covers Universal Credit, State Pension, Pension Credit, PIP, Housing Benefit, Council Tax Reduction, and more.

get-applicable-questions

Given partial answers, returns only the questionnaire sections and questions that apply. Use this to build a guided conversation — start with an empty answers object and add answers incrementally.

Available resources

URI Description
benefits://rates/2025-26 All benefit rates for the current tax year
benefits://questions Full list of questionnaire sections and questions
benefits://health Service health and uptime status
benefits://ctr-confidence Council Tax Reduction data confidence scores

Available prompts

benefits-assessment

A guided prompt that walks the AI through collecting user circumstances and running a full benefits calculation. Ideal for conversational benefit checks.

Sampling (guided data collection)

The MCP server supports sampling — a protocol feature where the server can ask the AI to perform a task during tool execution. When the calculate-benefits tool detects that essential information is missing (such as date of birth, postcode, or relationship status), it uses sampling to direct the conversation:

  1. The tool checks which critical fields are missing from the provided answers
  2. If the client advertises sampling capability, the server sends a sampling/createMessage request asking the AI to collect the missing information conversationally
  3. The AI generates a natural follow-up question explaining why each piece of data matters
  4. Once the user provides the information, the AI calls calculate-benefits again with the complete answers

Clients that do not support sampling receive a structured text response listing the missing fields and why they are needed, so the AI can ask the user directly.

Enabling sampling in your client

To use sampling, your MCP client must advertise the sampling capability during the initialize handshake: 

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "sampling": {}
    },
    "clientInfo": { "name": "my-client", "version": "1.0.0" }
  },
  "id": 1
}

Claude Desktop supports sampling automatically. Other MCP clients may need explicit configuration.

Skipping the data check

If you want to run the calculation immediately with whatever data is available, pass "skipDataCheck": true in the tool arguments. The calculator will use defaults for any missing fields (typically zero values).

Sessions

The server supports both session-based and stateless operation:

  • Session-based: Send an initialize request to start a session. The server returns a Mcp-Session-Id header. Include this header in all subsequent requests. Sessions enable sampling and persist for 30 minutes of inactivity.
  • Stateless: Send tools/call or tools/list directly without initialising. Each request is independent. Sampling is not available in this mode.

Authentication and rate limits

The MCP endpoint requires authentication. All requests must include a valid API key in the Authorization header. Authenticated requests are rate-limited to 120 requests per minute per API key.

If you already have an API key for the REST API v1, the same key works here. Otherwise, register for an account and create an API key from your dashboard.

Include the key in every request:

Authorization: Bearer bfk_your_api_key_here

Invalid or revoked API keys will receive a 401 error response.

Input constraints

The answers object accepted by both tools is validated against the same schema used by the web application:

  • Maximum of 100 answer fields per request
  • Values must be strings, numbers, booleans, null, date objects ({day, month, year}), or arrays of simple values
  • Prompt context is limited to 2,000 characters
  • Request payload is limited to 256 KB

Security practices

  • Error messages are sanitised — internal implementation details are not exposed to clients
  • No personally identifiable information is stored in usage logs
  • All tool outputs contain structured data only — no executable instructions
  • All tools are read-only (no data modification)

Claude Desktop configuration

To connect Claude Desktop to this MCP server, add the following to your claude_desktop_config.json file: 

{
  "mcpServers": {
    "uk-benefits-calculator": {
      "url": "https://missingbenefit.com/mcp",
      "headers": {
        "Authorization": "Bearer bfk_your_api_key_here"
      }
    }
  }
}

On macOS, this file is typically at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

Testing with curl

Initialise the MCP server:

curl -X POST https://missingbenefit.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer bfk_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": { "sampling": {} },
      "clientInfo": {
        "name": "curl-test",
        "version": "1.0.0"
      }
    }
  }'

Call a tool directly (each request is stateless):

curl -X POST https://missingbenefit.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer bfk_your_api_key_here" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get-applicable-questions",
      "arguments": { "answers": {} }
    }
  }'
Warning All calculations are estimates for the 2025/26 tax year. Do not rely on these results for actual benefit claims. Always verify through official government channels.