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.

Interactive data collection

When the calculate-benefits tool detects that essential information is missing (such as date of birth, postcode, or relationship status), the server will attempt to collect it interactively using the MCP protocol. The server tries three strategies in order:

  1. Elicitation (preferred) — if the client declares the elicitation capability, the server sends an elicitation/create request with a structured form. The client presents the form to the user and returns the answers directly. The server then merges the answers and runs the calculation automatically.
  2. Sampling — if elicitation is not available but the client declares the sampling capability, the server sends a sampling/createMessage request asking the AI to compose a conversational follow-up question for the user.
  3. Structured fallback — if neither elicitation nor sampling is available, the server returns a structured JSON response listing the missing fields with their IDs, questions, reasons, and priorities. The AI client can use this to ask the user directly and then call calculate-benefits again.

Enabling interactive collection in your client

To enable elicitation and/or sampling, your MCP client must advertise the relevant capabilities during the initialize handshake. A session-based connection is required. 

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

Elicitation is the preferred method as it collects data directly from the user and feeds it into the calculation in a single round-trip. Sampling asks the AI to compose a follow-up question, which requires an additional tool call to complete the calculation.

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 elicitation and sampling, and persist for 30 minutes of inactivity.
  • Stateless: Send tools/call or tools/list directly without initialising. Each request is independent. Elicitation and sampling are 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": { "elicitation": { "form": true }, "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.