Tutorial: OpenCorporates

Legal

Data source: OpenCorporates

Overview

OpenCorporates wraps OpenCorporates, 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-opencorporates": {
      "url": "https://context.gnist.ai/mcp/opencorporates/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_company`

Search the global company registry by name. Covers 200+ jurisdictions via the OpenCorporates database. Args: name: Company name or partial name to search for (e.g. "Apple", "Acme Corp"). jurisdiction: OpenCorporates jurisdiction code (e.g. "gb" for UK, "us_de" for Delaware, "no" for Norway, "de" for Germany). Omit for global search. status: Filter by company status: "Active", "Dissolved", "Inactive". Omit for all. max_results: Number of results to return (1–100, default 20). Returns: Dictionary with count and list of matching companies (registry_id, name, jurisdiction, status, incorporation_date, company_type, address). Use registry_id for details.

Parameter	Type	Required	Description
`name`	string	required	Company name or partial name to search for (e.g. "Apple", "Acme Corp").
`jurisdiction`	any	optional	OpenCorporates jurisdiction code (e.g. "gb" for UK, "us_de" for Delaware, "no" for Norway, "de" for Germany). Omit for global search.
`status`	any	optional	Filter by company status: "Active", "Dissolved", "Inactive". Omit for all.
`max_results`	integer	optional	Number of results to return (1–100, default 20). (default: `20`)

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

import httpx

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

`get_company_details`

Get full details for a specific company. Returns comprehensive information including registered address, industry codes, incorporation and dissolution dates, and company type. Args: registry_id: Company identifier in the format "{jurisdiction}/{company_number}", e.g. "gb/12345678" or "us_de/1234567". Obtained from search_company. Returns: Full company record, or {"error": "not_found"} if the registry ID is unknown.

Parameter	Type	Required	Description
`registry_id`	string	required	Company identifier in the format "{jurisdiction}/{company_number}", e.g. "gb/12345678" or "us_de/1234567". Obtained from search_company.

curl -X POST "https://context.gnist.ai/mcp/opencorporates/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_company_details", "arguments": {"registry_id": "gb/12345678"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/opencorporates/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'registry_id': 'gb/12345678'},
            'name': 'get_company_details'}},
)
print(resp.json())

`list_officers`

List directors and officers of a company. Returns all registered officers including directors, secretaries, and other roles where this information is publicly available. Args: registry_id: Company identifier in the format "{jurisdiction}/{company_number}", e.g. "gb/12345678". Obtained from search_company. Returns: Dictionary with count and list of officers (name, role, start_date, end_date, nationality, occupation, inactive flag).

Parameter	Type	Required	Description
`registry_id`	string	required	Company identifier in the format "{jurisdiction}/{company_number}", e.g. "gb/12345678". Obtained from search_company.

curl -X POST "https://context.gnist.ai/mcp/opencorporates/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_officers", "arguments": {"registry_id": "gb/12345678"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/opencorporates/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'registry_id': 'gb/12345678'},
            'name': 'list_officers'}},
)
print(resp.json())

`check_company_status`

Quick status check for a company by name. Returns the top matching company and its current status (active, dissolved, etc.). Useful for KYC pre-checks and supplier verification. Args: name: Company name to check (exact or near-exact match works best). jurisdiction: OpenCorporates jurisdiction code (e.g. "gb", "us_de", "no"). Strongly recommended to reduce ambiguity. Returns: Object with the best match company name, status, registry_id, and jurisdiction. Returns {"error": "not_found"} if no matches are found.

Parameter	Type	Required	Description
`name`	string	required	Company name to check (exact or near-exact match works best).
`jurisdiction`	any	optional	OpenCorporates jurisdiction code (e.g. "gb", "us_de", "no"). Strongly recommended to reduce ambiguity.

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/opencorporates/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'name': 'example'}, 'name': 'check_company_status'}},
)
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/opencorporates/" \
  -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/opencorporates/",
    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_company to find items, then get_company_details 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 OpenCorporates provide?

Global company search — incorporation data, officers, and filings across jurisdictions. It exposes 5 tools: search_company, get_company_details, list_officers, check_company_status, 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 OpenCorporates API return?

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