Tutorial: Companies House (UK)

Business

Data source: UK Companies House

Overview

Companies House (UK) wraps UK Companies House, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-companies-house": {
      "url": "https://context.gnist.ai/mcp/companies-house/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_uk_companies`

Search for UK companies by name on Companies House. Companies House is the UK's official company registry, covering 5+ million companies including PLCs, LTDs, LLPs, and foreign branches registered in England, Wales, Scotland, and Northern Ireland. Args: query: Company name to search for. limit: Number of results (1–100, default 10). Returns: Dict with 'count' and 'companies' list. Each result includes company_number, title, company_status, company_type, date_of_creation, and address_snippet.

Parameter	Type	Required	Description
`query`	string	required	Company name to search for (e.g. "Tesco", "Barclays", "Rolls-Royce").
`limit`	integer	optional	Number of results to return (1–100, default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/companies-house/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_uk_companies", "arguments": {"query": "Tesco"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/companies-house/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'Tesco'}, 'name': 'search_uk_companies'}},
)
print(resp.json())

`lookup_uk_company`

Look up a UK company by its Companies House company number. Returns the full company profile including name, status, type, SIC codes, registered address, jurisdiction, and previous names. Company numbers are 8 characters — numeric for English/Welsh companies, prefixed with SC (Scotland), NI (Northern Ireland), or other codes. Args: company_number: The Companies House company number. Returns: Dict with full company profile, or {"error": "not_found"} if not found.

Parameter	Type	Required	Description
`company_number`	string	required	UK company number (e.g. "00445790" for Tesco PLC, "SC123456" for a Scottish company).

curl -X POST "https://context.gnist.ai/mcp/companies-house/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "lookup_uk_company", "arguments": {"company_number": "00445790"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/companies-house/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'company_number': '00445790'},
            'name': 'lookup_uk_company'}},
)
print(resp.json())

`list_uk_company_officers`

List directors, secretaries, and other officers for a UK company. Returns current and past officers with their roles, appointment dates, nationality, and occupation. Resigned officers include their resignation date. Args: company_number: The Companies House company number. limit: Number of results (1–100, default 20). Returns: Dict with 'company_number', 'count', and 'officers' list.

Parameter	Type	Required	Description
`company_number`	string	required	UK company number.
`limit`	integer	optional	Number of officers to return (1–100, default 20). (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/companies-house/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_uk_company_officers", "arguments": {"company_number": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/companies-house/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'company_number': '12345'},
            'name': 'list_uk_company_officers'}},
)
print(resp.json())

`list_uk_company_filings`

List filing history for a UK company. Returns recent filings including accounts, annual returns, officer changes, and other regulatory submissions to Companies House. Args: company_number: The Companies House company number. category: Optional filter by filing category. limit: Number of results (1–100, default 20). Returns: Dict with 'company_number', 'count', and 'filings' list.

Parameter	Type	Required	Description
`company_number`	string	required	UK company number.
`category`	any	optional	Filter by filing category: "accounts", "officers", "address", "annual-return", "capital", "change-of-name", "incorporation", "liquidation", "miscellaneous", "mortgage", "resolution".
`limit`	integer	optional	Number of filings to return (1–100, default 20). (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/companies-house/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_uk_company_filings", "arguments": {"company_number": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/companies-house/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'company_number': '12345'},
            'name': 'list_uk_company_filings'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/companies-house/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/companies-house/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_uk_companies to find items, then lookup_uk_company to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Companies House (UK) provide?

UK Companies House — company search, profiles, officers, and filing history. It exposes 5 tools: search_uk_companies, lookup_uk_company, list_uk_company_officers, list_uk_company_filings, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Companies House (UK) API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.