Connect an agent

3 October 2026 00:09

Backlinks

Give an AI agent such as Claude Code or Cursor access to a LinkedDataHub instance over MCP, using Web-Algebra

Agents use the same HTTP API as the browser and the CLI. The bridge is Web-Algebra, which exposes LinkedDataHub operations as Model Context Protocol (MCP) tools: creating containers and items, adding views, queries and charts, reading and writing RDF, and running SPARQL. An agent connected this way can build a working application in a dataspace — its classes, containers, views and charts are documents like any other.

The conventions agents should follow when writing to LinkedDataHub are in AGENTS.md.

Prerequisites

A running LinkedDataHub instance. The examples below assume the default local setup at https://localhost:4443/.
The WebID certificate the agent will act as. For your own instance that is the owner certificate, ssl/owner/cert.pem, with the password from secrets/owner_cert_password.txt. The agent can do whatever that WebID is authorized to do.
uv, which runs Web-Algebra without a separate install step.

Claude Code

claude mcp add web-algebra \
  --env CERT_PEM_PATH="$PWD/ssl/owner/cert.pem" \
  --env CERT_PASSWORD="$(cat secrets/owner_cert_password.txt)" \
  -- uv run --with web-algebra python -m web_algebra

Start claude and check that /mcp lists web-algebra as connected.

Cursor and Claude Desktop

Both read an mcpServers entry: ~/.cursor/mcp.json for Cursor, claude_desktop_config.json for Claude Desktop. Use absolute paths and the literal password, since these files are not run by a shell.

{
  "mcpServers": {
    "web-algebra": {
      "command": "uv",
      "args": ["run", "--with", "web-algebra", "python", "-m", "web_algebra"],
      "env": {
        "CERT_PEM_PATH": "/path/to/LinkedDataHub/ssl/owner/cert.pem",
        "CERT_PASSWORD": "your-owner-cert-password"
      }
    }
  }
}

If the client cannot find uv, replace "uv" with its absolute path, as printed by which uv.

Streamable HTTP transport

Clients that connect to an MCP URL instead of launching a process can use Web-Algebra's HTTP server:

CERT_PEM_PATH="$PWD/ssl/owner/cert.pem" \
CERT_PASSWORD="$(cat secrets/owner_cert_password.txt)" \
uv run --with web-algebra uvicorn web_algebra.server:app

The MCP URL is http://127.0.0.1:8000/mcp. For Claude Code: claude mcp add --transport http web-algebra http://127.0.0.1:8000/mcp.

The HTTP server does not authenticate its callers, and it holds your WebID certificate. Anyone who can reach the port acts as you. Keep it bound to 127.0.0.1, which is the default, and do not expose it on a network.

Try it

Ask the agent for something small that it has to declare rather than code, for example:

Create a container for books in my dataspace, add three books with authors, and add a chart of books per author.

Then open https://localhost:4443/ in the browser. The container, the items and the chart are there, and you can keep editing them by hand — the agent and you work on the same documents.