Skip to content
Browse documentation

MCP server

The Model Context Protocol (MCP) endpoint is the native integration path for AI agents. Instead of writing HTTP calls, an agent connects to the Rotuli MCP server and calls its registered tools.

Endpoint

The MCP server is hosted by the API and requires authentication:

https://api.rotuli.co.uk/mcp

MCP accepts a bearer API key or an OAuth access token issued through the MCP connector flow. OAuth here authorises MCP access; this page does not describe OAuth authentication for the REST API.

Quota behaviour

A tools/callrequest consumes one request from the active key's monthly quota, except a call to get_account_status, which is not counted. Protocol traffic such as initialize, tools/list, and ping does not. The reserved resources/read and prompts/get methods are chargeable if called, although no handlers are registered for them today.

Once a key's quota is exhausted, the endpoint returns HTTP 429 even for otherwise uncharged protocol messages. This keeps the exhausted key from continuing to use the MCP endpoint without a remaining quota.

Connect from Claude

The simplest way to connect in Claude is the Rotuli listing in the Claude Connectors Directory. Open the listing, or search for Rotuli under Customize, then Connectors, in Claude, and choose Connect. The connector signs you in through the flow described below; there is no URL to type and no API key to copy. Rotuli is listed as a Community connector.

For another client, or to add the server by hand, use the endpoint URL above in the client's remote custom-connector UI and continue through its authorisation flow. In Claude, follow Anthropic's current remote custom connector instructions for the UI steps; clients choose their own configuration format, so this page intentionally provides the URL rather than a universal JSON or Claude Desktop snippet.

The connector flow signs in by email magic link. Open that link in the same browser that requested it, then use its explicit confirmation button; opening the link alone does not complete sign-in. After you approve access, authorised apps appear in your dashboard under Connected apps, where you can withdraw access at any time.

An OAuth-connected MCP session resolves to your highest-tier active key at request time, so a tier change takes effect without reconnecting. If the account has no active key, the connector cannot be used.

What the agent gets

Six tools are registered. Each has a human-readable title and is marked read-only; none of them changes data.

  • lookup_uk_company (Look up UK company, all plans) — fetch a full company profile by Companies House number.
  • search_uk_companies (Search UK companies, all plans) — search by company name.
  • get_company_risk (Get company risk signals, Growth and Enterprise) — fetch risk signals only for a company number.
  • get_officer_appointments (Get officer appointments, Growth and Enterprise) — fetch appointments for one Companies House officer ID.
  • get_company_control_graph (Explore corporate control graph, Growth and Enterprise) — explore corporate controllers and related companies with evidence paths and coverage.
  • get_account_status (Get account status, all plans) — report the plan tier, the tools available on it and the remaining monthly quota. Calls to it do not count towards the quota.

The officer-appointments, risk, and control-graph tools require a Growth or Enterprise key. An ineligible call returns an error field with appointments_tier_required , risk_tier_required, or control_graph_tier_required as JSON text content, together with current_tier, the plan of the key the connection uses. Appointment results are scoped to one Companies House officer ID, not a person-level identity across officer IDs.

Each tool returns its own compact JSON as MCP text content. The response shape therefore depends on the tool: company lookup returns a profile, risk returns a company number plus risk signals, search returns a query, result list, and total_results. Tool-level errors are JSON text too. Do not assume that every tool includes source-accountability fields. See the API Reference for the underlying REST data models and the risk-signal code table.

Server instructions

The server identifies itself as rotuli. Its initialize response carries instructions written for the connection: they name the plan of the key in use, the tools available on that plan, and the tools that need another plan. Tool descriptions are the same on every plan; only these instructions vary.

Checking the account

get_account_status takes no arguments and returns:

  • tier — the plan of the key the connection uses.
  • available_tools and tier_gated_tools — the tools this plan can and cannot call.
  • usage — used, limit, remaining and resets_at(ISO 8601, UTC) for the key's current monthly window. These are the same figures as the REST rate-limit headers.

The call is not counted towards the quota, but once the quota is spent it is refused with HTTP 429 like every other message. It returns no email address or key details.

Land holdings in company lookups

On Growth and Enterprise, lookup_uk_company includes HM Land Registry titles in land_holdings, ordered newest first by date_added, with undated titles last. The optional land_limit argument (an integer from 1 to 200) sets how many titles are returned; it defaults to 25. The REST endpoint, by contrast, returns every title unless ?land_limit= is passed.

land_summary sits beside land_holdings and always counts every title the company holds, whatever the limit: total_count, returned_count, freehold_count, leasehold_count and truncated. truncated is true when titles were left out; call again with a larger land_limit to get more. When land was not requested or could not be fetched, land_holdings is empty and every count is zero; check sources_checked and sources_failed to tell the cases apart.

A land_limit that is not an integer from 1 to 200 returns invalid_land_limit. Land data is never returned on its own: a sources value that leaves only land returns land_requires_combination; add another source, for example ch,land. See error codes.

Using the company control graph

Call get_company_control_graph with company_number. The optional direction is group by default, adding indexed controlled companies to the subject and its ancestors. Use ancestors to follow corporate controllers only. max_depth and max_nodes accept positive integers up to your tier limits: 4 levels and 12 nodes for Growth; 6 levels and 24 nodes for Enterprise.

The tool returns the same graph model as REST: nodes, edges, related_risk, coverage, frontier, limits and usage. Inspect discovery and assessment coverage before interpreting an empty finding list. A partial graph keeps the available evidence and explains stops such as missing index coverage, unresolved identifiers, node limits or upstream capacity.

Corporate PSCs are ordinary registry facts. Related-company dissolution or insolvency findings stay separate from the subject’s risk score. Discovery is bounded corporate PSC evidence, not a complete ownership, beneficial-owner or liability determination.

Errors remain JSON text content. invalid_control_graph_options requires corrected options; control_graph_capacity includes retry_after in seconds. A graph tool call counts as one request, including a returned tool error. See the rate limits for account and traversal budgets.

When to use MCP vs REST

Use MCP when the caller is an agent that speaks the protocol — it handles tool discovery and tool calls natively. Use the REST API when you are writing your own integration, running batch pipelines, or need raw HTTP control. Both use the active key's applicable quota and tier gates.