Companies House MCP Server

A comprehensive Know Your Business (KYB) toolkit via Model Context Protocol (MCP). This server provides 22 production-ready tools that integrate with the UK Companies House API to enable complete due diligence automation, beneficial owner discovery, risk detection, and regulatory compliance.

Status: ✅ Production Ready | Version: 2.0.0 | Tools: 22 (17 new + 5 backward compatible) | API Endpoints: 16

# 🎯 The 10 KYB Requirements (All Implemented)

| # | Requirement | Tools | Status |
|- --|- -- -- -- -- -- --|- -- -- --|- -- -- -- -|
| 1️⃣ | Filing History | get_filing_history_list(), get_filing_history_item() | ✅ |
| 2️⃣ | Filing Item by Transaction ID | get_filing_history_item() | ✅ |
| 3️⃣ | Document Download via MCP | download_document(), download_filing_document() | ✅ |
| 4️⃣ | PSC (Beneficial Owners) - Full Set | get_psc_list(), get_psc(), get_psc_statements() | ✅ |
| 5️⃣ | Charges (Mortgages/Security) | get_charges_list() | ✅ |
| 6️⃣ | Insolvency (MANDATORY KYB) | get_insolvency() | ✅ |
| 7️⃣ | Registered Office Address (Direct) | get_registered_office_address() | ✅ |
| 8️⃣ | Officer Appointments (Director Network) | get_officer_appointments() | ✅ |
| 9️⃣ | Officer Disqualifications (MANDATORY) | get_disqualification_natural(), get_disqualification_corporate() | ✅ |
| 🔟 | Advanced Company Search | search_companies_advanced() | ✅ |

# Features

# # Core KYB Capabilities

• ✅ Company Search & Verification: Advanced search by name, number, or address with fuzzy matching
• ✅ Company Profiles: Complete company details (status, address, incorporation date)
• ✅ Insolvency Detection (MANDATORY): Hard-stop risk signal for any credit/partnership decision
• ✅ Officer Verification: Directors, secretaries with complete appointment history
• ✅ Disqualification Checks (MANDATORY): Screen natural persons and corporate entities
• ✅ Beneficial Owner Discovery (PSC): Identify Persons with Significant Control with ownership %
• ✅ Officer Network Analysis: Detect serial directors and company connections
• ✅ Registered Office Address: Direct verification without parsing full profile
• ✅ Filing History & Documents: Access accounts, confirmations, PSC notifications with PDF download
• ✅ Charges & Mortgages: View secured lending exposure and creditor priorities
• ✅ Comprehensive Reports: Single-call KYB aggregation (search → verify → risk-check → report)

# # Operational Excellence

• Production Ready: All 10 requirements implemented, tested, documented
• Complete API Coverage: 16 Companies House endpoints fully integrated
• Pagination Support: Handle large result sets across all list tools
• Error Standardization: Consistent error responses with codes and descriptions
• Backward Compatible: 5 legacy tools maintained for existing integrations
• Stateless Design: No data stored, secure for public cloud deployment
• Rate Limiting: Passes through Companies House rate limits with error codes
• Base64 Documents: PDFs returned with metadata for secure transmission

# # Use Cases

• Know Your Business (KYB): Complete 10-requirement compliance for company onboarding
• Risk Assessment: Insolvency detection, disqualification screening, charge analysis
• Due Diligence: Deep research via filing history, document access, officer networks
• Beneficial Owner Verification: UBO identification with control percentages
• Serial Director Detection: Map director networks across companies
• Compliance Reporting: Generate audit trails and risk assessments

# 📚 Documentation

Getting Started: Start with one of these based on your needs:

• QUICK_REFERENCE.md - 5-minute overview of all 10 requirements
• INDEX.md - Complete documentation index and navigation hub
• IMPLEMENTATION_SUMMARY.md - Comprehensive implementation guide
• API_ENDPOINT_MAPPING.md - Complete API-to-tool reference
• REQUIREMENTS_IMPLEMENTATION.md - Detailed requirement mapping
• CHECKLIST.md - Verification checklist

# 🔄 Complete KYB Workflow

This is what a full Know Your Business process looks like using the server:

1. Search for company
   → search_companies_advanced("Company Name")
   
2. Verify correct company
   → get_company_profile(company_number)
   
3. ⚠️  CHECK INSOLVENCY (MANDATORY - HARD STOP IF FOUND)
   → get_insolvency(company_number)
   
4. Get company details
   → get_registered_office_address(company_number)
   → get_filing_history_list(company_number)
   
5. Get officers
   → get_company_officers(company_number)
   → For each officer:
      • get_disqualification_natural(officer_id)  [RED FLAG]
      • get_officer_appointments(officer_id)      [NETWORK]
   
6. Get beneficial owners (PSC)
   → get_psc_list(company_number)
   → For each PSC:
      • get_psc(company_number, psc_id)
      • Check disqualifications
   → get_psc_statements(company_number)
   
7. Get financial exposure
   → get_charges_list(company_number)           [MORTGAGES]
   
8. Review documents if needed
   → get_filing_history_list(company_number)
   → download_filing_document(company_number, transaction_id)
   
9. Generate final report
   → generate_company_report(company_number)

Result: Complete due diligence report with all compliance checks passed ✅

# Architecture

• Transport: HTTP (Stateless Streamable) - Ideal for public/cloud deployment.
• Authentication: Client-side API Key injection (users provide their own key).
• Stack: Python, FastMCP, Docker, Kubernetes.

# Prerequisites

1. Companies House API Key: You must obtain a "Live" API Key from the Companies House Developer Hub.
2. Docker (for local running).
3. Kubernetes (optional, for deployment).

# Quick Start (Docker)

1. Build the Image:

   docker build -t companies-house-mcp .
   

2. Run the Container:

   docker run -p 8001:8001 companies-house-mcp
   

3. Test with Postman:

   • Import mcp_postman_collection.json.
   • Set the apiKey variable to your Companies House API Key.
   • Send a POST request to http://localhost:8001/mcp.

# Usage with Claude Desktop (or other MCP Clients)

Configure your MCP client to connect to the server. Since this server uses HTTP transport, you might need an adapter or a client that supports HTTP MCP.

Tool Call Example (JSON-RPC):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_company_report",
    "arguments": {
      "company_number": "00000006",
      "api_key": "YOUR_REAL_API_KEY"
    }
  }
}

# Tools Reference

# # All 22 Available Tools

# # # Company Search & Profile (3 tools)

| Tool | Description | Key Args |
|- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -|
| search_companies_advanced | Advanced search: name, number, or address | q, items_per_page, start_index |
| get_company_profile | Full company details | company_number |
| get_registered_office_address | Direct office address access | company_number |

# # # Filing & Documents (4 tools)

| Tool | Description | Key Args |
|- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -|
| get_filing_history_list | List all filings with pagination | company_number, category, items_per_page |
| get_filing_history_item | Get specific filing by transaction ID | company_number, transaction_id |
| download_document | Download document by ID | document_id |
| download_filing_document | Download filing (lookup + download wrapper) | company_number, transaction_id |

# # # Officers & Management (2 tools)

| Tool | Description | Key Args |
|- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -|
| get_company_officers | List directors and secretaries | company_number, items_per_page |
| get_officer_appointments | Get all appointments for an officer | officer_id, items_per_page |

# # # Beneficial Owners (PSC) (3 tools)

| Tool | Description | Key Args |
|- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -|
| get_psc_list | List beneficial owners (Persons with Significant Control) | company_number, items_per_page |
| get_psc | Individual PSC details with ownership info | company_number, psc_id |
| get_psc_statements | PSC statements (e.g., "no PSCs", "unknown") | company_number, items_per_page |

# # # Risk & Compliance (3 tools)

| Tool | Description | Key Args |
|- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -|
| get_insolvency | ⚠️ MANDATORY: Check insolvency proceedings | company_number |
| get_disqualification_natural | 🚩 MANDATORY: Check natural person disqualification | officer_id |
| get_disqualification_corporate | 🚩 MANDATORY: Check corporate disqualification | officer_id |

# # # Security & Assets (1 tool)

| Tool | Description | Key Args |
|- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -|
| get_charges_list | List charges/mortgages (secured lending) | company_number, items_per_page |

# # # Comprehensive Reports (1 tool)

| Tool | Description | Key Args |
|- -- -- -|- -- -- -- -- -- --|- -- -- -- -- -|
| generate_company_report | Full KYB aggregation (Best for agents) | company_number |

# # # Backward Compatibility (5 deprecated tools)

search_companies, get_filing_history, get_company_charges, get_persons_with_significant_control, get_company_insolvency
(Still available but use new tools above)

# Deployment (Kubernetes)

1. Deploy:

   kubectl apply -f k8s/deployment.yaml
   kubectl apply -f k8s/service.yaml
   

   (Note: The secret.yaml is no longer strictly required if you rely on client-side keys, but can be used for server-side defaults).

2. Access:
   The service is exposed via NodePort on port 30001 (or LoadBalancer depending on your K8s setup).

# Security Note

This server is designed to be stateless. It does not store your API keys. Keys are passed per-request or configured via environment variables (optional fallback). Ensure you transmit keys over HTTPS in production.

# Companies House API Endpoints Used

# # Company Information

• GET /company/{company_number} - Full company profile
• GET /company/{company_number}/registered-office-address - Office address
• GET /company/{company_number}/officers - Officers list
• GET /company/{company_number}/filing-history - Filing history with transaction IDs
• GET /company/{company_number}/filing-history/{transaction_id} - Individual filing item
• GET /company/{company_number}/charges - Charges/mortgages
• GET /company/{company_number}/insolvency - Insolvency status

# # Persons with Significant Control (PSC)

• GET /company/{company_number}/persons-with-significant-control - PSC list
• GET /company/{company_number}/persons-with-significant-control/{type}/{id} - Individual PSC
• GET /company/{company_number}/persons-with-significant-control-statements - PSC statements

# # Officer Management

• GET /officers/{officer_id}/appointments - Officer's appointments

# # Disqualifications

• GET /disqualified-officers/natural/{officer_id} - Natural person disqualifications
• GET /disqualified-officers/corporate/{officer_id} - Corporate disqualifications

# # Document Access

• GET /document/{document_id}/content - Download document content

# # Search

• GET /search/companies - Company search with filters

# Implementation Notes

# # Authentication

All API calls use HTTP Basic Authentication with your Companies House API Key.

# # Rate Limiting

The MCP server passes through rate limit errors (HTTP 429). Implement exponential backoff in client applications.

# # Error Handling

• 404 NOT_FOUND: Resource doesn't exist or has been removed.
• 401 UNAUTHORISED: Invalid or missing API key.
• 429 RATE_LIMIT: Too many requests. Retry after delay.
• 5xx API_ERROR: Server error with response body.

# # Document Downloads

Document downloads are returned as base64-encoded content with metadata including:

• document_id: The document identifier
• content_type: MIME type (e.g., application/pdf)
• content_length: File size in bytes
• content_base64: Base64-encoded file content