The machine inhabits the syntax

01

What it is

MCP (Model Context Protocol) is the open protocol that connects a language model to external tools. The dwfw server has two transports over the same logic: stdio for local development (mcp/index.mjs) and Streamable HTTP for production, at https://dwfw.trabemflex.com/mcp. Both translate each call from the agent into requests to the core's REST API — the same one documented in the API guide, with the same permissions.

The division of roles is doctrinal: the machine inhabits the syntax; the human, the semantics. A connected agent can detect formal patterns and propose connections; a human curator confirms or discards them in the panel. The server grants no powers: the core's RBAC decides, through the service user with the investigador role.

What a connected agent can do, today: search and read works, authors and nodes, walk the cartography, consult the Event Stack programme, and propose connections between works and nodes (they arrive as proposals, machine provenance). What it cannot: confirm those proposals, assign meanings, advance curatorial movements, or see or touch users, credentials or private assets. The recommended connection is one-click OAuth 2.1 (like HubSpot or Slack connectors): you authorize with your DWFW user on a consent screen and the client is connected, with no tokens to copy; every session belongs to a person, shows up in the audit log, expires on its own and is revoked in the admin. A token-based alternative remains for clients that do not speak OAuth.

02

One-click connection (OAuth)

The recommended way. The server implements OAuth 2.1 with dynamic client registration and PKCE — the same flow as HubSpot or Slack connectors: you authorize with your DWFW user on a consent screen and the client is connected, with no hand-copied tokens. Every session belongs to a person (the audit log records their email), can be revoked in the admin (MCP sessions) and expires on its own: 1-hour access the client renews for up to 30 days.

• claude.ai (web or desktop): Settings → Connectors → "Add custom connector" → URL https://dwfw.trabemflex.com/mcp → authorize on the DWFW screen.
• Claude Code: the command below; the browser opens the consent screen and once you authorize, the session is connected.

# Claude Code: no token, no headers — your browser opens the DWFW consent screen
claude mcp add --transport http dwfw https://dwfw.trabemflex.com/mcp

# After authorizing it should show ✔ Connected
claude mcp list

03

Remote connection with a token (alternative)

The production transport is Streamable HTTP and it is stateless: every request is self-contained, with no sessions or client affinity. If you cannot use OAuth, the manual alternative is a client token (next section); it always travels in the Authorization header, never in the URL.

# Claude Code: connect to the remote server (token from the next section)
claude mcp add --transport http dwfw https://dwfw.trabemflex.com/mcp \
  --header "Authorization: Bearer dwfw_mcp_…"

# Check the service health (no credentials)
curl https://dwfw.trabemflex.com/mcp/salud

# Other MCP clients with remote HTTP: generic configuration
{
  "mcpServers": {
    "dwfw": {
      "url": "https://dwfw.trabemflex.com/mcp",
      "headers": { "Authorization": "Bearer dwfw_mcp_…" }
    }
  }
}

04

Remote authentication

The client token (dwfw_mcp_…) is issued with an API call under a direction session: POST https://dwfw.trabemflex.com/api/tokens-mcp with {"nombre": "who uses it"}. The plaintext token comes ONLY in that JSON response — copy it then; only its hash is stored and it can never be read again. Unticking "Active" in the admin revokes it (effective within ≤1 minute); the optional expiry switches it off by itself.

Three identities that never mix: the token identifies the remote client; the MCP server talks to the API as maquina@dwfw.test with an internal key that never leaves the server; and permissions come from that user's RBAC. OAuth sessions coexist with these tokens: same transport, same tools, same RBAC barrier.

05

Local connection (stdio)

You need Node 18+ and a copy of the repository. The server needs no database or local configuration: only environment variables pointing at the API. In Claude Desktop, add the JSON block below to claude_desktop_config.json.

# Clone the core and install the server dependencies (Node 18+)
git clone https://github.com/juanceldran/dwfw-core
cd dwfw-core/mcp && pnpm install --ignore-workspace

# Run by hand (it speaks stdio; normally the MCP client launches it)
DWFW_API_URL=https://dwfw.trabemflex.com/api DWFW_API_KEY=… node index.mjs

# Claude Code: register the server (adjust the path to your copy of the repository)
claude mcp add dwfw \
  -e DWFW_API_URL=https://dwfw.trabemflex.com/api \
  -e DWFW_API_KEY=… \
  -- node /ruta/dwfw-core/mcp/index.mjs

# Check that it shows up and connects
claude mcp list

{
  "mcpServers": {
    "dwfw": {
      "command": "node",
      "args": ["/ruta/dwfw-core/mcp/index.mjs"],
      "env": {
        "DWFW_API_URL": "https://dwfw.trabemflex.com/api",
        "DWFW_API_KEY": "…"
      }
    }
  }
}

06

Credentials and variables

The recommended way is an API key of the service user maquina@dwfw.test (investigador role): it is generated in the admin, on the user's sheet, by ticking "Enable API Key". It is sent as the Authorization: usuarios API-Key … header and avoids storing passwords in client configurations. The alternative is DWFW_EMAIL + DWFW_PASSWORD (the server refreshes the JWT by itself).

Without credentials, the server works in public read-only mode: the archive (works in movement 7), authors, nodes, the cartography, meanings and the Event Stack programme. Proposing connections requires a service session.

# Core API (production; in development, http://localhost:3000/api)
DWFW_API_URL=https://dwfw.trabemflex.com/api

# API key of the service user (recommended; generated in the admin)
DWFW_API_KEY=…

# Alternative: a session with the service user's email and password
DWFW_EMAIL=maquina@dwfw.test
DWFW_PASSWORD=…

# Default language of the responses: es · en · zh · ja
DWFW_LOCALE=es

07

Tools

Six read tools and a single write. Names and parameters are technical identifiers and are not translated; the content does arrive in the language requested with locale.

dwfw://doctrina — Read-only resource with the hard rules of the core in markdown. A client can load it into context before the agent starts working.

08

What it can and cannot do

The limits are not promises of the agent: the core server enforces them on every request. The service user has read capabilities plus conexion:proponer; any other write receives a 403 with an explicit message. Even if the agent tries, the core forbids it.

It can

• ● Read the whole observatory (works in any movement), authors, nodes, connections, meanings and the Event Stack programme.
• ● Search and filter by text, type, movement or state, in any of the four languages (locale).
• ● Propose connections between works and/or nodes (any combination of origin and target) with syntactic evidence in nota: they are born with maquina provenance and propuesta state.
• ● Read the dwfw://doctrina resource to know the rules before acting.

It cannot

• ● Confirm or discard connections: that is a semantic act and requires the conexion:confirmar capability (403 with an explicit message).
• ● Assign meanings (layer 4): it requires significado:asignar, a capability reserved for human curators (403); the server also enforces procedencia: humano on every meaning.
• ● Advance curatorial movements: the state of a work only changes with movimiento:avanzar.
• ● Create, edit or delete works, authors, nodes, editions or users; nor upload or publish Media assets.
• ● Request or infer popularity metrics: there are no likes, views or rankings in the API (algorithmic epoché).

# Propose a connection: it is born as a proposal, with machine provenance
proponer_conexion {
  "origen":  { "tipo": "obras", "id": 3 },
  "destino": { "tipo": "nodos", "id": 2 },
  "tipoRelacion": "dialoga_con",
  "nota": "Both work with simulated biological growth: mycelium as generative logic."
}
# → { "ok": true, "id": 12, "estado": "propuesta", "procedencia": "maquina",
#     "mensaje": "Propuesta registrada. Queda pendiente de confirmación humana." }

# See the proposals awaiting human confirmation
cartografia { "estado": "propuesta" }

09

Protocol versions

The HTTP transport serves the revisions supported by the official SDK: 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. Clients on the 2026-07-28 revision — which makes the protocol stateless, as this server already is — probe and negotiate down by themselves (recent Claude Code does). Adopting it once the SDK ships it will be a dependency bump, not a redesign.

10

Doctrine for agents

Before working, the agent should load the dwfw://doctrina resource. In short:

• Provenance in every layer: what the machine proposes remains a proposal until a human confirms it.
• Algorithmic epoché: the weight of the idea sets the order; there are no metrics to optimise or request.
• The seven movements: only a human advances the curatorial state; of the works, only movement 7 (the archive) is public without a session.
• Cultural origin is descriptive data, never an ordering or hierarchy criterion.
• Technical assets are private until movement 7 (blind curation).