BORME API

BORME API MCP connector

*Español: README.es.md*

Connect Microsoft Copilot, Claude, ChatGPT, Cursor, VS Code or any MCP client to the hosted BORME API MCP server: Spanish commercial-registry data published in the BORME (Boletín Oficial del Registro Mercantil), with more than 9.6 million events since 2009, company histories, company search by name, NIF lookup, trademarks and trading names, and risk signals.

The server is hosted at mcp.bormeapi.com; there is nothing to install or run, and it is the recommended way to connect. This repository holds what you need around it: connection settings for each client, an agent skill, the event-type vocabulary, and a local stdio server that wraps the BORME API REST endpoints, for clients that only start servers over stdio.

The full guide, kept up to date, is at bormeapi.com/mcp. If this README and that page ever disagree, the page is right.

Two ways to connect

API key: `https://mcp.bormeapi.com/mcp`

• Transport: Streamable HTTP. Each request gets a plain JSON response; no session is kept between calls.
• Authentication: your API key in the X-API-Key header. Without a key, the free plan's limits apply.
• For clients that can send a header: Microsoft Copilot Studio, Claude Code, Cursor, VS Code, Claude Desktop (through mcp-remote) and any other Streamable HTTP client.

OAuth: `https://mcp.bormeapi.com/mcp/oauth`

• For assistants with custom connectors that sign in with OAuth, such as Claude.ai, ChatGPT or Copilot. There is no API key to paste anywhere: you sign in with your BORME API account, and the app uses the plan of the account that authorized it.
• This endpoint requires a BORME API account and ignores the X-API-Key header. Its calls share your API key's daily quota with REST API and /mcp calls made with that key.
• If your account has no active API key, the tools return an error directing you to your account page; they work again once your account has an active key, without reconnecting the app.
• If the app does not use the connection for 30 days, connect it again. You can disconnect the app at any time under Connected apps on your account page.
• For client developers: an unauthenticated call gets 401 with WWW-Authenticate: Bearer resource_metadata="https://mcp.bormeapi.com/.well-known/oauth-protected-resource/mcp/oauth". The authorization server is https://bormeapi.com (metadata at /.well-known/oauth-authorization-server), with dynamic client registration, PKCE (S256) and the scope mcp.

Get an API key on your account page.

Set up your client

Claude.ai (OAuth)

1. Go to Customize > Connectors > Add custom connector.
2. Enter https://mcp.bormeapi.com/mcp/oauth as the server URL. Claude detects how to sign in and shows Sign in now and Register automatically; keep these options.
3. Click Add. Our sign-in page opens.
4. Sign in with the link we email you, then select Allow.
5. Back in Claude, if the connector page says the connector has no tools, reload the page.

On Team and Enterprise plans an owner adds the connector under Organization settings.

To use your API key instead, enter https://mcp.bormeapi.com/mcp, choose No sign-in and add the x-api-key header with your key under Request headers. Anthropic offers request headers as a beta to a limited set of organizations; if you do not see that section, use the Claude Desktop setup below.

ChatGPT (OAuth)

ChatGPT's custom connectors cannot send an API-key header. Add a custom connector with https://mcp.bormeapi.com/mcp/oauth as the server URL and sign in with your BORME API account. The screens and their names may differ from Claude.ai's. Without OAuth, ChatGPT can use https://mcp.bormeapi.com/mcp only without a key, on the free plan.

Microsoft Copilot Studio and Microsoft 365 Copilot (API key)

These steps follow Microsoft's documentation. They may vary with your tenant and your data loss prevention (DLP) policies.

1. In Copilot Studio, open the agent you want to use and go to Tools > Add a tool > New tool > Model Context Protocol.
2. Enter a Server name (BORME API), a Server description and the Server URL: https://mcp.bormeapi.com/mcp
3. For authentication, choose API key, set Type to Header and enter X-API-Key as the header name. Select Create, then Create a new connection, enter your key and select Add to agent.
4. Test the agent in Copilot Studio first. Then publish it and set up the Teams and Microsoft 365 Copilot channel, subject to your organization's permissions and policies. If your organization has Power Platform data policies (DLP), an administrator may need to allow this connector.

Claude Code (API key)

claude mcp add --transport http --scope user \

--header "X-API-Key: YOUR_KEY" \ borme https://mcp.bormeapi.com/mcp

--scope user makes the server available in all your projects; leave it out to add it to the current project only.

Cursor (API key)

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project) and set BORME_API_KEY in your environment:

{

"mcpServers": { "borme": { "url": "https://mcp.bormeapi.com/mcp", "headers": { "X-API-Key": "${env:BORME_API_KEY}" } } } }

VS Code (API key)

Add this to .vscode/mcp.json in your workspace. VS Code asks for the key the first time the server starts:

{

"inputs": [ { "type": "promptString", "id": "borme-api-key", "description": "BORME API key", "password": true } ], "servers": { "borme": { "type": "http", "url": "https://mcp.bormeapi.com/mcp", "headers": { "X-API-Key": "${input:borme-api-key}" } } } }

Claude Desktop (API key)

Add the server to claude_desktop_config.json through mcp-remote, a third-party bridge that needs Node.js:

{

"mcpServers": { "borme": { "command": "npx", "args": ["mcp-remote", "https://mcp.bormeapi.com/mcp", "--header", "X-API-Key:${BORME_API_KEY}"], "env": { "BORME_API_KEY": "YOUR_KEY" } } } }

Any other Streamable HTTP client (API key)

Send each JSON-RPC message as a POST to https://mcp.bormeapi.com/mcp with Content-Type: application/json, an Accept header that includes application/json, and your key in X-API-Key. For example, to list the tools:

curl -s https://mcp.bormeapi.com/mcp \

-H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "X-API-Key: YOUR_KEY" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Local stdio server

server.py is a local stdio server that wraps the BORME API REST endpoints; the hosted server at mcp.bormeapi.com is the recommended way. It offers the same tools, with the same names, titles, descriptions, parameters and annotations (all tools are read-only), as the hosted server: they are copied into tools.json. Each tool call makes one or more requests to https://api.bormeapi.com/v1/.... It holds no data; MCP directories build an image from its Dockerfile to list the tools.

• Listing the tools needs no key and no network.
• Calling a tool needs an API key for every tool except list_act_types and registry_stats: the REST API, unlike the hosted MCP server, has no keyless free plan. Your free key is in your account. Set it as BORME_API_KEY.
• daily_digest and registry_stats return fewer fields than on the hosted server, because the REST API has no single endpoint for them: daily_digest returns the day's event count, its parse completeness and up to 200 insolvency notices, and registry_stats returns the latest publication date and, with a key, the parse completeness of the last 30 publication days.
• It does not sign in with OAuth.

With Docker:

docker build -t borme-mcp .

docker run -i --rm -e BORME_API_KEY=YOUR_KEY borme-mcp

With Python 3.12:

pip install -r requirements.txt

BORME_API_KEY=YOUR_KEY python server.py

When the hosted server changes its tools, run python scripts/update_tools.py to regenerate tools.json and commit it. CI fails while tools.json and the hosted server differ.

Tools

• search_companies - find companies by current or former name and get ranked company cards.
• company_history - the registry timeline of one company: the published acts available under your plan, newest first.
• search_events - search BORME notices by date, province, act type and company name.
• daily_digest - one publication day in figures, with its insolvency notices.
• company_by_nif - find a company by its NIF/CIF tax ID (Basic plan and above).
• brand_owner - find the company a trademark or trading name is linked to (Basic plan and above).
• company_brands - trademarks and trading names linked to one company (Basic plan and above).
• recent_signals - the latest risk signals, such as insolvency filings and mass exits (Risk plan).
• list_act_types - the act types, with their English labels and the original Spanish headings.
• registry_stats - size and coverage of the registry data.
• company_snapshot - a company profile with officers, sole shareholder and capital (Basic plan and above).
• company_signals - one company's derived signals, with date and type filters (Pro plan and above).
• act_stats - act counts by type, period and province, including mergers, spin-offs and capital increases (Pro plan and above).

Each tool's description and parameter schema, as returned by tools/list, explain its parameters.

Prompts and resources

Besides tools, the hosted server and the local stdio server offer prompts, ready-made instructions that your client can offer you (in Claude, from the + menu; in other clients, wherever they list a server's prompts), and resources, reference data that your client can attach as context. A prompt only supplies the instructions: the tool calls it leads to count against your plan as usual.

• company_due_diligence (company): a report on one company's identification, published history, officer appointments and insolvency notices, citing the BORME id of each act.
• board_changes (company, since): appointments, re-elections, terminations and resignations, revocations and ex officio cancellations of appointments, optionally since a date.
• new_companies_digest (province, date): companies whose incorporation notices were published in BORME on one day, for one province or autonomous community. If date is omitted, it uses the latest publication day.
• check_nif (nif): which company a NIF/CIF is linked to in our data, and its latest published acts (Basic plan and above).
• visit_briefing (company): a briefing for a client visit, with a company profile and its history and signals from the last 24 months.

The prompts tell the model to cite BORME ids, to tell a name match from a confirmed identification or ownership, and not to treat a missing result as proof that something does not exist.

• borme://act-types: the act types, as list_act_types returns them.
• borme://provinces: the provinces and autonomous communities that the province filters accept. It needs BORME_API_KEY; without a key, reading the resource returns instructions for obtaining a free API key.
• borme://coverage: data freshness, as registry_stats returns it on this