@entryscape/mcp-server

EntryScape MCP Server

An MCP server that exposes the EntryScape API as tools, so an agent can read and write EntryScape data — catalogs, datasets, distributions and the rest of the DCAT-AP surface — over stdio.

It is generated from the EntryScape OpenAPI specification: one tool per operation, with the operation's parameters as the tool's input schema. Nothing here is edited by hand.

Requirements

Node 20 or newer.

Installing

The package is on npm, and MCP servers are normally launched straight from there, so nothing has to be installed first:

npx -y @entryscape/mcp-server

It is also listed in the MCP Registry as com.entryscape/mcp-server, which is where clients and marketplaces look it up. npm install -g @entryscape/mcp-server works too and puts an entryscape-mcp binary on PATH.

Without npm, every release is also published as an archive at https://api.entryscape.com/sdk/latest/mcp-server.tar.gz. It ships prebuilt, so only its runtime dependency has to be installed:

mkdir entryscape-mcp && tar -xzf mcp-server.tar.gz -C entryscape-mcp
cd entryscape-mcp && npm install --omit=dev

The launch command is then node dist/bin/entryscape-mcp.js rather than npx -y @entryscape/mcp-server.

Running it with no ENTRYSCAPE_API_URL stops it with a message naming the variable — see Configuration below.

Configuration

All configuration is environment variables. They are read and validated once at startup, so a bad value stops the server with a message naming the variable rather than failing on the first tool call.

Variable	Required	Default	Purpose
ENTRYSCAPE_API_URL	yes	—	Base URL of the EntryScape API server, path included (e.g. https://api.entryscape.com)
ENTRYSCAPE_AUTH_TOKEN	no	—	Session token, sent as X-Auth-Token. Without it the server runs as a guest: reads work, writes are refused
ENTRYSCAPE_REQUEST_TIMEOUT_MS	no	30000	Per-request timeout
ENTRYSCAPE_MAX_RESPONSE_BYTES	no	262144	Largest response body handed to the client; a longer body is cut with an explicit marker
ENTRYSCAPE_ENTRYSTORE_HOST	no	—	EntryStore instance the API server should use, sent as X-Entrystore-Host (e.g. dev.entryscape.com/store/). Unset leaves the API server's own default
ENTRYSCAPE_MCP_TAGS	no	—	Comma-separated spec tags to serve tools for (e.g. dataset,catalog,search). Unset serves all of them
ENTRYSCAPE_MCP_UPLOAD_ROOT	no	—	Directory the upload tools may read files from. Unset means uploads are disabled
ENTRYSCAPE_MCP_MAX_UPLOAD_BYTES	no	10485760	Largest file an upload tool will send

One server process talks to one EntryStore, so the instance is configuration here rather than an argument on every tool — which is what it used to be, at a cost of about a fifth of the tool list.

ENTRYSCAPE_API_URL has no default on purpose. A default would point at one deployment, and a client that had simply forgotten to configure the variable would read and write there without saying so.

Results

Every tool returns the response body as text. When the body is a JSON object, the same value is also returned as structuredContent, so a client can use the result as data without parsing a blob. A body that was truncated at the response cap is text only — it is no longer valid JSON.

Tools do not declare an outputSchema by default. The schemas are large enough to matter: declaring them for this API adds about 93 kB to a 178 kB tool list, which every client pays for on connect whether or not it validates anything.

What the server tells the model

The initialize response carries a short instructions string, which MCP clients hand to the model once per connection. It holds the rules that are true for every tool and that a model meeting this API for the first time tends to get wrong: the token is bound to one EntryStore instance and the server cannot log in; entries are addressed by context and entry id; the search index lags a write, so a create is re-read by id rather than repeated; metadata updates replace the whole graph; uploads return a job that has to be polled.

It is a paragraph, not a manual — workflows that span several tools belong in skills, not here — and it describes the build, so it names the upload tools even when ENTRYSCAPE_MCP_TAGS leaves them out of the running server. The text is templates/sdk/mcp/instructions.md in the EntryScape API repository; the build embeds it and checks that every tool it names exists.

Choosing which tools to expose

A client pays for the whole tool list on every connection, and this API is large. ENTRYSCAPE_MCP_TAGS narrows it without rebuilding anything: name the tags you want and the server registers only those tools. Ten of the tags are model-* — the Models API — which most consumers never touch.

A tag the server has no tools for is a startup error listing the ones it has, rather than a server that quietly offers nothing.

Uploads

Three tools take a local file path — addFileToDistribution, replaceFileInDistribution and importTerminology. That path is chosen by the model, so the server will only read files under ENTRYSCAPE_MCP_UPLOAD_ROOT, which has no default: without it the tools refuse and say so.

Point it at a directory holding the files you intend to publish, and nothing else. Paths are resolved through symlinks before the check, so a link inside the root cannot reach out of it, and a file above the size cap is refused before it is read. Files uploaded to a distribution may be publicly reachable, so treat the root as material you are willing to publish.

Redirects are never followed: the session token travels in a custom header, which fetch would carry across origins, so a 3xx is reported as an error instead.

Running

npm install
npm run build
ENTRYSCAPE_API_URL=https://api.entryscape.com node dist/src/index.js

MCP client configuration

Most clients take a command, its arguments and an environment block. From npm, which needs no checkout and no install step:

{
  "mcpServers": {
    "entryscape": {
      "command": "npx",
      "args": ["-y", "@entryscape/mcp-server"],
      "env": {
        "ENTRYSCAPE_API_URL": "https://api.entryscape.com",
        "ENTRYSCAPE_AUTH_TOKEN": "your-session-token"
      }
    }
  }
}

Pin a version with @entryscape/mcp-server@1.2.0 in place of the bare name; without one, npx takes the newest published.

For a local checkout, point "command": "node" at /path/to/mcp-server/dist/src/index.js instead. The package also installs an entryscape-mcp binary, so "command": "entryscape-mcp" works wherever it is on PATH.

Skills

skills/ holds consumer skills: procedures that span several tools, which no single tool description can carry — finding entries and summarizing them with facets (find), publishing a dataset from catalog to validated distribution (publish-dataset), editing an existing entry without dropping the rest of its metadata (edit-metadata), or migrating an integration off the Taskrunner API (migrate-from-taskrunner). Each is a directory with a SKILL.md in the Agent Skills format (name and description frontmatter, then the procedure), which Claude Code and a growing number of other clients load on demand, so a skill costs nothing until it is needed.

The skills say in which order to call the tools and what to check between calls. They do not repeat what the tool descriptions already say, and they are checked at build time: every tool a skill names must exist in this build, so a skill cannot outlive an operation it depends on.

Claude Code plugin

This directory is also a Claude Code plugin — .claude-plugin/plugin.json and .mcp.json — so one install gives the server and the skills together. Claude Code installs plugins from marketplaces only, so the directory carries a one-entry marketplace pointing at itself:

npm install --omit=dev      # the server's runtime dependency
claude plugin marketplace add /path/to/mcp-server
claude plugin install entryscape@entryscape --scope user

To try it for one session without installing, start Claude Code with --plugin-dir /path/to/mcp-server instead.

The registration passes ENTRYSCAPE_API_URL, ENTRYSCAPE_AUTH_TOKEN, ENTRYSCAPE_ENTRYSTORE_HOST, ENTRYSCAPE_MCP_TAGS and ENTRYSCAPE_MCP_UPLOAD_ROOT through from the environment Claude Code was started in; set the ones you need there. An unset URL is refused by the server with a message naming the variable, as it is when run by hand. Other clients that read the Agent Skills format can be pointed at skills/ directly and configured for the server as in the previous section.

Authentication

ENTRYSCAPE_AUTH_TOKEN is the only way to authenticate this server. Obtain a token from the API server's POST /auth/login — it is valid for the EntryStore instance that issued it — put it in the environment, and restart.

The API's /auth/* operations are deliberately not exposed as tools. A login tool could not install its token anywhere: the server reads the token once, at startup, so the call would report success and every later call would still be unauthenticated. logout would work, and would invalidate the very token the server was configured with. Keeping credentials out of a tool call also keeps them out of the model's context.

Licence

LGPL-3.0-or-later. See the EntryScape API repository for the full text.