MCP server

Introduction

The Model Context Protocol is an open standard for how an AI agent reaches external tools and data. Instead of programming an interface, you add the server once to the agent's configuration. From then on the model knows which tools exist and calls them itself when the conversation needs them.

Our server exposes the same data as the REST API: filings, company profiles, financial figures, insolvency practitioners, statistics and the watchlist. The difference is the framing. The tool descriptions are written so a model understands when an insolvency check makes sense, which details it has to ask for and where the limits of the data lie.

The address is https://insolvencyradar.com.au/api/mcp. It uses the same keys as the REST API. Operate both side by side and you will see the same watchlist in both.

Access

The route is the same as for the REST API: keys are issued by hand. Use the contact form or write to [email protected] and say briefly which agent you want to connect and what it should do.

If you already have an API key, you do not need a second one: the same key opens the MCP server. Teams that want to hand the server to several people can receive several keys on one account, so it stays traceable who checked what.

Connection and transport

The server speaks MCP over Streamable HTTP, the transport current clients use by default. No local process is needed, there is nothing to install.

Authentication uses the same header as the REST API: X-API-Key, alternatively Authorization: Bearer. Like the API key itself, the server is bound to its market: the server on insolvencyradar.com.au answers about companies in Australia. Clients that only speak stdio reach it through mcp-remote as a bridge, see the Claude Desktop configuration below.

Client and server negotiate the protocol version when connecting. We support the current revision and the one before it, so a client update never leads to a hard break.

curl https://insolvencyradar.com.au/api/mcp/health

Setup

In Claude Code one command is enough. The key should come from an environment variable, not from the clipboard.

claude mcp add --transport http insolvencyradar \
  https://insolvencyradar.com.au/api/mcp \
  --header "X-API-Key: $INSOLVENCY_API_KEY"

Claude Desktop

Claude Desktop reads its server list from claude_desktop_config.json. The entry bridges to the HTTP transport via mcp-remote.

{
  "mcpServers": {
    "insolvencyradar": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://insolvencyradar.com.au/api/mcp",
        "--header", "X-API-Key:${INSOLVENCY_API_KEY}"
      ],
      "env": { "INSOLVENCY_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Cursor and other clients

Cursor, Windsurf, Zed and most other clients take the server URL directly and allow their own headers, so no bridge is needed.

{
  "mcpServers": {
    "insolvencyradar": {
      "url": "https://insolvencyradar.com.au/api/mcp",
      "headers": { "X-API-Key": "${env:INSOLVENCY_API_KEY}" }
    }
  }
}

After adding it, the client should show eleven tools. If the list stays empty, it is almost always the header: a lapsed or mistyped key produces an empty tool list rather than a visible error.

Tools

The server provides eleven tools. Writing tools are marked as such, so clients can ask for confirmation where they want to.

All reading tools are idempotent and may be called without asking. watch_company and unwatch_company change your account and announce themselves to the client as writing tools.

check_counterparty in detail

The tool that matters is check_counterparty. Its schema is deliberately narrow: a name or a company number, optionally the town and a start date. The fewer decisions a model has to make, the less often it invents values.

{
  "name": "check_counterparty",
  "description": "Check whether a company in Australia appears in official insolvency filings. Use before extending credit, signing a supplier or chasing an overdue invoice. Prefer the company number over the name when you have it. Never guess a company number.",
  "annotations": { "readOnlyHint": true },
  "inputSchema": {
    "type": "object",
    "properties": {
      "name":           { "type": "string", "description": "Company name as written on the invoice or contract." },
      "city":           { "type": "string", "description": "Registered town, narrows ambiguous names." },
      "company_number": { "type": "string", "description": "National register number, e.g. 14839205" },
      "since":          { "type": "string", "format": "date", "description": "Only filings on or after this date. Default: 3 years ago." }
    },
    "anyOf": [ { "required": ["name"] }, { "required": ["company_number"] } ]
  }
}

The description tells the model explicitly to prefer the company number and never to guess one. A wrong number leads to a confident "no filing" for the wrong company, which is worse than an ambiguous answer.

If a name is not unique, the tool does not pick one but returns an error text with the number of candidates. The model then asks the user for the town or the company number. This behaviour is intentional and is covered in the error handling section.

Without since, the tool looks back three years. Older proceedings are usually closed and no longer relevant for current decisions; if they are, pass an earlier date.

Response format

Tools answer on two tracks: a text block for the model and structuredContent for the client. The text block is worded so the model can pass it on without interpreting it first: company, company number, procedure type, date, court or register, reference and source.

{
  "content": [
    {
      "type": "text",
      "text": "SAMPLEWORTH JOINERY LIMITED (14839205, Leeds): Compulsory liquidation filed on 2026-09-28. Issued by Companies House, reference 1. Source: Companies House."
    },
    {
      "type": "resource_link",
      "uri": "insolvency://company/14839205/filings",
      "name": "Filings of SAMPLEWORTH JOINERY LIMITED",
      "mimeType": "application/json"
    }
  ],
  "structuredContent": {
    "match": "exact",
    "company_number": "14839205",
    "status": "liquidation",
    "filings": [
      { "date": "2026-09-28", "type_code": "compulsory-liquidation", "case_number": "1" }
    ]
  },
  "isError": false
}

Long material such as the full filing history comes back as a resource link, not embedded. A client that wants to show it resolves the link; one that does not keeps its context window small.

Resources

In addition to tools, the server provides resources under the insolvency:// scheme. Clients that support resources can display them or attach them to the model without calling a tool.

insolvency://company/{number}              company profile and status
insolvency://company/{number}/filings      all filings of a company
insolvency://company/{number}/financials   published accounts figures
insolvency://practitioner/{id}             appointed practitioner or office
insolvency://watchlist                     your watched companies
insolvency://types                         filing types with keys and aliases

The watchlist resource changes when a new filing concerns a watched company. The server then sends a change notification, so clients can update their view.

Prompts

For recurring tasks there are ready-made prompts. They collect what the task needs and then call the appropriate tools. In clients that support prompts they appear as quick commands.

{
  "name": "counterparty_check",
  "description": "Check a list of customers or suppliers for insolvency filings and summarise the risk.",
  "arguments": [
    { "name": "companies", "description": "One company per line: name, town or company number.", "required": true },
    { "name": "since",     "description": "Look-back start date, default 3 years.", "required": false }
  ]
}

Currently available are counterparty_check (check a list of companies), weekly_briefing (new filings of the week for selected regions or industries) and company_timeline (history of a company's insolvency explained in plain language). If you prefer your own flow, ignore the prompts and call the tools directly.

Example conversation

This is what it looks like in practice. The agent checks three customers, explains the results in plain terms, asks back where the name is ambiguous and then sets up the monitoring.

User:   Check these three customers before we renew their credit lines:
        SAMPLEWORTH JOINERY LIMITED, BRIGHTWELL LOGISTICS LTD, HARBOUR LANE FOODS LIMITED.

Agent:  [check_counterparty name="SAMPLEWORTH JOINERY LIMITED"]
        [check_counterparty name="BRIGHTWELL LOGISTICS LTD"]
        [check_counterparty name="HARBOUR LANE FOODS LIMITED"]

Agent:  SAMPLEWORTH JOINERY LIMITED (14839205, Leeds): Compulsory liquidation
        recorded on 2026-09-28, reference 1, Companies House.
        I would not renew the credit line.

        BRIGHTWELL LOGISTICS LTD: no insolvency filing in the last three years.

        HARBOUR LANE FOODS LIMITED: two companies carry that name. Which town is
        your customer in?

User:   Bristol.

Agent:  [check_counterparty name="HARBOUR LANE FOODS LIMITED" city="Bristol"]
        No filing for the company in Bristol.
        Shall I put all three on the watchlist, so you hear about
        any new filing straight away?

User:   Yes.

Agent:  [watch_company company_number="14839205" ref="SAMPLEWORTH JOINERY LIMITED"]
        [watch_company name="BRIGHTWELL LOGISTICS LTD"]
        [watch_company name="HARBOUR LANE FOODS LIMITED" city="Bristol"]
        Done. All three are on the watchlist.

The important step is the third one: for an ambiguous name, the agent asks instead of choosing. That is exactly what the error text of the tool is designed for.

Permissions

Each key carries permissions. By default it can read filings, companies, practitioners and statistics; writing to the watchlist must be enabled separately.

Tools for which the key has no permission do not appear in the tool list at all. That is friendlier than an error mid-conversation, because the model then never offers something it cannot do.

Error handling

Errors come back as a normal tool result with isError: true, not as a protocol error. The text is addressed to the model and says what it should do next, so the agent can react sensibly inside the conversation.

{
  "content": [
    {
      "type": "text",
      "text": "No unique match: 2 companies are called \"HARBOUR LANE FOODS LIMITED\". Ask the user for the town or the company number and call check_counterparty again. Do not pick one yourself."
    }
  ],
  "isError": true
}

Real protocol errors only occur with an invalid key, a missing permission or a malformed request. Everything that can go wrong on the content side, such as an ambiguous name, an unknown company number, an unknown procedure type or a period longer than 31 days, comes back as text.

Limits

The same limits apply as for the REST API: 120 tool calls per minute and key, at most 31 days and 10,000 rows per search in filings, 24 months in statistics. For higher values an email is enough.

Exceeding a limit does not produce a hard error but a text result saying when it can continue. Agents should then wait rather than call again immediately.

Data and responsibility

The server returns public insolvency data, which can contain personal data. The same rules apply as for the REST API: data protection law, no reselling of the raw data, no automated decisions about natural persons based solely on this data.

An agent may summarise a filing, but it does not replace legal advice. The tool texts therefore always name the court or register and the reference, so the user can check the original. We recommend that your agent also points this out when it derives recommendations for action.

What the agent sends to the server (company names, your references) is used only to answer the request and is not passed on. If your agent processes data about your customers, a data processing agreement is available.

Operations

The server runs on the same infrastructure as the REST API. Maintenance windows are announced by email to the stored address, and changes to tool schemas are additive only.

When a new tool is added, the server sends a change notification. Clients that react to it see the tool without restarting. Existing tools keep their names and their required fields.

Support

Questions, higher limits, your own prompts or tools for a specific workflow: [email protected] or the contact form.

If you prefer to work against plain HTTP, the same data is documented as a REST interface in the API documentation. Both routes share keys, limits and contract.