MCP server

What an MCP server is

MCP — Model Context Protocol — is an open protocol through which an assistant gets tools: look up a concept, create a cohort, add a widget. Linkr’s MCP server turns each of these tools into calls to Linkr’s API, as the app itself would.

It holds no language model and hosts no conversation. That is the client’s job — LibreChat, OpenCode or any other MCP-compatible assistant — which picks the model, shows the conversation and asks for your approval before acting.

Step 1 — Create your API key

An API key lets an external client act as you without your password. You create it in Linkr:

The key list shows each key’s creation date, last use, expiration and status — Active, Expired or Revoked. Revoke cuts a key off for good: the Linkr API refuses it at once, and the MCP server, which briefly remembers keys it has already checked, at most a minute later.

A key has exactly your permissions, no more, no less. It cannot, however, create, list or revoke keys: even stolen, it cannot mint others or prevent its own revocation.

Step 2 — Run the MCP server

This step belongs to the instance’s administrator, once for the whole institution: a single MCP server serves every user, each with their own key.

With Docker, the repository’s docker/docker-compose.yml file runs the MCP server as a separate service, mcp, beside the app: it listens on port 3940 and is already wired to the API. The docker/docker-compose.hub.yml file, the one a production install uses, runs it the same way from the image published on Docker Hub.

Without Docker, the server runs from a copy of the repository — the packages/linkr-mcp folder —, with Node.js, after an npm install at the root:

cd packages/linkr-mcp
echo "LINKR_API_URL=https://linkr.my-hospital.org" > .env   # your Linkr instance's address
npm run start:http                                          # → http://127.0.0.1:3940/mcp

LINKR_API_URL is the only setting needed: your instance’s address, or http://localhost:8000 when the MCP server runs on the same machine as the backend. If LibreChat runs in Docker on the same machine, add LINKR_MCP_HOST=0.0.0.0: it then reaches the server at http://host.docker.internal:3940/mcp. LINKR_MCP_PORT changes the port.

On a development install, npm run dev:all already starts the MCP server with the rest of Linkr — see Manual install.

Step 3 — Plug it into your client

Linkr works with any MCP-compatible client, but we recommend open-source tools, driven by a model hosted in the institution: the Agents page explains why.

LibreChat

In LibreChat, add an MCP server with:

• URL — the server’s address, for example http://127.0.0.1:3940/mcp;
• Transport — Streamable HTTP;
• Authentication — API key, Bearer format;
• Each user provides their own key — ticked. LibreChat then asks each user for their key, and the server acts as them.

LibreChat’s administrator must also allow the server’s address in librechat.yaml, under mcpSettings.allowedDomains. They can declare the server there for every user as well:

mcpSettings:
  allowedDomains:
    - "127.0.0.1"

mcpServers:
  linkr:
    type: streamable-http
    url: http://127.0.0.1:3940/mcp
    headers:
      Authorization: "Bearer {{LINKR_API_KEY}}"
    customUserVars:
      LINKR_API_KEY:
        title: "Linkr API key"
        description: "User settings → API keys, in Linkr"

librechat.yaml is also where confirmation before a tool runs is set. Linkr’s tools state whether they read, modify or delete, so reads can be let through and the rest confirmed.

OpenCode

OpenCode is an open-source agent that works in a terminal — including the project’s IDE one — and can use a local model. Declare the Linkr server in its configuration as a remote MCP server: the server’s address, and the Authorization: Bearer lnk_… header with your key.

Any other MCP-compatible client connects to the HTTP server the same way.

What the agent sees in Linkr

Once connected, the agent has over two hundred tools, grouped by area: warehouse, cohorts, concepts, datasets, dashboards, IDE and environments, concept mapping, quality, ETL, data catalog, wiki, documentation. The Agents page presents them with example requests.

Each change made by the agent refreshes the open Linkr tabs and is listed in the Notifications bell — “Added by MCP” —, with a link to the item and, for some, Undo.

The documentation, with no setup

Two tools let the agent search this documentation and read a page, to answer a question about how Linkr works while citing the source. The server reads the documentation published on this site and keeps it up to date on its own. Without internet access, it falls back to a copy shipped with it, and warns the agent that it may be less recent.

Going further

• Agents — what an agent can do, and how you stay in control.
• Skills — installing the concept-mapping skill in LibreChat.
• Deployment modes — why an install with a backend is needed.