Skip to content

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 UK company lookup, risk signals, and search as tools.

Endpoint

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

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

Access is gated by the same credentials as the REST API — an API key (bearer token) or an OAuth grant from the connector flow. Every call counts against the owning key's monthly quota.

Connect from an MCP client

Any MCP-capable client can connect. For clients that read a JSON config (such as Claude Desktop), add a server entry pointing at the endpoint:

{
  "mcpServers": {
    "rotuli": {
      "url": "https://api.rotuli.co.uk/mcp"
    }
  }
}

In clients with a built-in connector flow (for example a custom connector in claude.ai), paste the endpoint URL when prompted and complete the OAuth authorization. Authorized apps appear in your dashboard under Connected apps, where you can withdraw access at any time.

What the agent gets

The MCP tools mirror the REST endpoints, so an agent can:

  • Fetch a full entity profile for a UK company number
  • Fetch risk signals only — score, triggered flags, and indeterminate flags
  • Fetch every UK company appointment held under a single Companies House officer ID, with derived counts of how many of those companies are dissolved or in insolvency (phoenix-pattern signals)
  • Search for companies by name

The officer-appointments tool (get_officer_appointments) is Growth/Enterprise only — a free key gets back a clean appointments_tier_required error object rather than a thrown error. Results are scoped to the single officer ID you pass: Companies House does not unify people across officer IDs, so this is the appointment history of that officer record, not necessarily the complete history of the underlying person.

Responses follow the same guarantees as the REST API: every field always present, stable enums, and sources_checked / sources_failed on every response. See the API Reference for full schemas and the risk-signal code table.

When to use MCP vs REST

Use MCP when the caller is an agent that speaks the protocol — it handles tool discovery and structured calls natively. Use the REST API when you are writing your own integration, running batch pipelines, or need raw HTTP control. Both are backed by the same data and quotas.