Skip to research content

Use OpenInsider in your AI client

The Model Context Protocol (MCP) lets a compatible AI client search OpenInsider and read regulatory records through tools. The connector uses your API key and keeps the access rules of your account.

The connector currently runs from a source checkout. There is no managed public MCP endpoint yet. For a remote connection, use an endpoint supplied by your operator.

Connect a local client

Use this option when your MCP client can launch a local process over stdio. You need Python 3.10 or later, uv, access to the connector source and a platform API key.

  1. Create an API key

    Open your account’s API section to create or manage a key. Key availability follows your plan. Keep it in your client’s private configuration or secret environment.

    Manage API keys
  2. Install the connector

    Obtain a connector checkout through your OpenInsider contact. From the checkout root, install its locked dependencies. Replace the example path below with the absolute path on the machine running your AI client.

    Install from a checkoutshell
    cd /absolute/path/to/openinsider
    uv sync --project backend/mcp --frozen
  3. Add the server to your MCP client

    In a client that accepts mcpServers JSON, add this entry. Replace the checkout path and the sample key. A server configured over stdio is started by the client when it connects.

    Local MCP configurationjson
    {
      "mcpServers": {
        "openinsider": {
          "command": "uv",
          "args": [
            "run",
            "--project",
            "/absolute/path/to/openinsider/backend/mcp",
            "--frozen",
            "openinsider-mcp"
          ],
          "env": {
            "OPENINSIDER_API_URL": "https://api.openinsider.eu/api/v2",
            "OPENINSIDER_API_KEY": "<your-platform-api-key>"
          }
        }
      }
    }

    Enter the API key in the MCP client’s configuration, never in a conversation or a tool argument.

  4. Connect and check the tools

    Reconnect your client and look for the OpenInsider tools. Start with list_jurisdictions to check disclosure coverage, then search_entities to find a company or person. Other clients may use a different configuration format; use the same command, arguments and environment values.

Try a research question

Ask the client to find the company first and use the canonical ID returned by search. The prompts below describe a workflow; results depend on your key and the available data.

Follow a company’s disclosed activity

Find Banco Santander in OpenInsider. Use the returned issuer ID to list its latest effective filings. Show the reported amounts in their original currencies and link to the source filings.

Typical tools: search_entities, get_issuer and list_filings.

Explore disclosed relationships

Find a company in OpenInsider, read its relationship network and explain which people or entities are linked to it. Include the source records and distinguish reported roles from assumptions.

Typical tools: search_entities and get_issuer_network.

A filing query, as tool arguments

Call list_filings with a filters object. The ID shown here is illustrative: replace it with the ID returned by search, without changing its punctuation.

list_filings argumentsjson
{
  "filters": {
    "issuer_id": "issuer:es:example",
    "amendment_scope": "effective",
    "limit": 25
  }
}

Lists return up to 25 records by default, with a maximum of 100. When has_more is true, pass next_cursor as filters.cursor with the same filters. Ask for one page at a time.

Use amendment_scope: effective for current filing leaves. transaction_scope can be all, shares or investment. These scopes select reported activity; they do not establish personal investment intent.

16 tools for reading the platform

All tools read the existing API. Filing detail includes public regulator and document links; downloading a PDF as binary content is outside this connector.

list_jurisdictionslist_marketsget_market_summary
National disclosure coverage, exchange/listing coverage and the market activity summary. Disclosure coverage does not imply price coverage.
search_entities
Company and person suggestions with canonical IDs. Name searches need at least three characters.
list_issuersget_issuer
The company directory and company profiles, with identifiers and reported activity.
list_insidersget_insider
The insider directory and source-backed person or entity profiles.
list_filingsget_filing
Regulatory disclosures, participants, operations and public provenance links.
list_transactionsget_transaction
Individual operations, direction, instruments and original amounts and currencies.
get_issuer_networkget_insider_network
The platform’s bounded relationship graphs for companies and insiders.
get_issuer_price_history
Available normalized company price history. Availability depends on the instrument, source and coverage.
get_signals_overview
The current analytical overview. Requires active Signals Pro and an available snapshot.

Connect to a remote server

Use Streamable HTTP if your operator has supplied a reachable MCP endpoint and your client can send a bearer header. Replace the example URL with that endpoint, including its /mcp path.

Remote MCP configurationjson
{
  "mcpServers": {
    "openinsider": {
      "url": "https://your-mcp-host.example/mcp",
      "headers": {
        "Authorization": "Bearer <your-platform-api-key>"
      }
    }
  }
}

The .example URL is a placeholder, not an OpenInsider service address. A normal browser visit is not an MCP connection.

Each caller supplies their own platform API key. This connection uses manual bearer authentication; it does not provide an OAuth browser sign-in flow.

HTTP authentication adds a coverage-catalog API read to every authenticated request, including connection and tool discovery. Tool calls also use the normal API quota.

Your account’s access still applies

  • Free keys retain their single-issuer restriction. Supplying an issuer ID can pin a Free account that has not selected an issuer yet.
  • The Signals overview requires an active Pro entitlement. A connected MCP client does not unlock data outside your plan.
  • Check list_jurisdictions and list_markets for current coverage and limitations. Missing price history or a missing analytical snapshot does not mean there are no disclosures.
  • Amounts keep the API’s decimal strings and currencies. Missing values mean unknown, not zero. Ask for source links and coverage limits alongside conclusions.
  • The connector does not manage accounts, billing or API keys, run ingestion or provide website-only features.

If a request fails

401 · API key
Check that the key is valid and has not been revoked. Use OPENINSIDER_API_KEY for stdio, or the Authorization bearer header for HTTP.
403 · Access denied
Check your plan and pinned issuer. The Signals overview requires active Pro.
429 · Quota reached
Wait for the indicated retry_after_seconds before trying again. For HTTP, include authentication reads when estimating usage.
404 / 503 · Data unavailable
The record, price history or analytical snapshot may be unavailable. Check coverage and try again later if the API reports a temporary outage.
Invalid tool arguments
Use IDs exactly as returned by the API, keep page sizes between 1 and 100 and include a timezone in date filters. Use a cursor only with the filters that produced it.
REST API guide