feat: expose JSS as an MCP server (--mcp) — proposed v0.0.200 #490
Description
Why
The agent ecosystem (Claude Desktop, Cursor, custom agents, …) has no shared answer for sovereign, ACL-gated storage. Every agent today bolts on its own DB, vector store, or secrets vault. Solid's pitch — user-owned data, queryable, access-controlled — is exactly what agents need, but the wire connecting them doesn't exist yet.
MCP (Model Context Protocol) is becoming that wire. If JSS speaks MCP, every MCP-compatible agent gets a sovereign data layer for free, with WAC, WebIDs, and Nostr identities all already in place.
Thesis statement: "MCP needs a backend. Solid is the backend."
This is the proposed v0.0.200 capstone — completing the feature-development phase before consolidation.
What
```bash
jss start --mcp # exposes /mcp endpoint speaking MCP
```
Initial tools
Tiny surface to start; expand once the foundation is in:
| Tool | Maps to |
|---|---|
| `list_resources` | LDP container GET (lists `ldp:contains`) |
| `read_resource` | GET resource (any content type, including JSON-LD) |
| `write_resource` | PUT / POST resource |
| `subscribe` | Existing JSS WebSocket notifications wrapped as MCP events |
Deferred: `query` (SPARQL or JSON-LD frame), `delete_resource`, `patch_resource`.
Auth
Reuse existing JSS layers — no new auth code:
- WebID-OIDC + DPoP — for Claude Desktop and other browser-OIDC agents
- NIP-98 — for Nostr-native agents
- Bearer token — for headless agents / CI
The MCP server enforces WAC the same way every other JSS endpoint does. `acl:agent did:agent:claude` can grant a specific agent specific resources. `acl:agentClass` with a new `acl:Agent` term could grant agent-class-wide access.
Wire format
MCP supports stdio, HTTP+SSE, and WebSocket transports. HTTP+SSE is the natural fit — JSS already serves HTTP, and SSE composes with the existing notification infrastructure. Stdio is irrelevant (JSS is a long-running daemon).
Scope estimate
~500 lines. The protocol is thin, JSS already has all the backend primitives. The work is an adapter layer:
- MCP handshake (initialize, list_tools, capabilities)
- Tool dispatch (route MCP tool calls to existing JSS internals)
- SSE event stream wrapping the WS notification pipe
Why it's distinctive
- No other Solid server has this
- No other MCP server has WAC, WebID, or sovereign storage
- The combination is what's unique — Solid's strength (data sovereignty) becomes MCP's missing piece
Acceptance
- `jss start --mcp` exposes `/mcp` endpoint
- Claude Desktop can register the endpoint as an MCP server and read/write a resource
- WAC applies: agent without `acl:Write` gets 403 on `write_resource`
- `subscribe` emits events on resource changes via SSE
- Tested end-to-end with at least one external MCP-compatible client
- `docs/mcp.md` covers wiring up Claude Desktop / generic MCP clients
Out of scope (for v0.0.200)
- `query` tool (deferred to v0.0.201+)
- Agent-class WAC term (`acl:Agent`) — proposed but not blocking
- MCP "prompts" or "resources" surface (we expose tools first)
- Local LLM hosting / inference inside JSS
Activity
melvincarvalho commented on May 18, 2026
Charlie as the use case — MCP as the first-class API for deployed bots
Reframing this issue so the user-visible payoff comes first, with MCP as the substrate that makes it possible.
The thesis
Once a pod runs MCP, any deployed bot — Charlie, a forum-moderator, a calendar agent, a research assistant — gets a uniform way to:
What Charlie looks like
<pod>/private/bots/charlie/ SKILL.md # "You are Charlie, a helper bot. Your owner is <webid>. # When asked X, do Y. Tools are at /mcp." config.jsonld # bot identity (did:nostr:...), model preference, etc. memory/ # conversation history, learned facts <pod>/public/apps/charlie/ # the user-facing chat UI (a solid-apps repo)Owner opens /public/apps/charlie/, logs in via xlogin, chats. The UI POSTs prompts to the LLM (BYO key) which is configured to use the pod's /mcp endpoint as its tool surface. Every action Charlie takes is WAC-gated against Charlie's did:nostr: agent identity — owner can revoke /private/finance/ access with one ACL edit and Charlie no longer sees it.
Why this framing matters
The boring framing: "JSS speaks MCP." Capability-equivalent but framed at the wrong level — MCP is plumbing, no one buys plumbing.
The Charlie framing: "JSS 0.0.200: your pod now has bots." MCP is the footnote that makes it portable. Same bot code works on every JSS pod because every JSS pod speaks the same protocol — that's the network effect.
It also makes JSS the first pod server where agent identity is a first-class WAC subject. Granting an agent access to a resource is the same operation as granting a human access to a resource. That's a genuinely novel primitive — and it's only possible because the Solid stack already has identity, ACL, and resource-orientation. MCP just exposes it to agents.
Updated acceptance criteria
Inspiration: TimBL on agent-pod interaction — https://www.w3.org/DesignIssues/Works.html
melvincarvalho commented on May 18, 2026
Cross-reference: #205 already raised this in March under "Agent Charlie — AI assistant with Solid pod data access," citing the same TimBL link. Same vision, different architecture.
#205's shape (server-owned agent):
This issue's shape (pod as tool surface):
Both compose. `/mcp` is the lower primitive; `/agent/` (#205) could be built on top of it later as a JSS-hosted convenience for users who don't want to run their own LLM client.
Proposal: keep #205 open as the user-facing "Charlie as a hosted service" follow-on. Land #490's `--mcp` substrate first because it's the foundation everything else builds on.
melvincarvalho commented on May 18, 2026
Folding SKILL.md into the MCP design (extensible + future-proofed)
Making skill discovery a first-class concern of the MCP server, not an afterthought a bot has to figure out.
Convention
Skills live at well-known paths the MCP server knows about:
This is the minimum convention. The MCP server walks these paths and exposes them via dedicated tools — the bot doesn't have to know the convention to find skills, the MCP server does that for it.
Format: SKILL.md vs SKILL.jsonld (future-proofing)
Both are first-class:
The MCP server returns both when listing. Each entry declares its format:
```json
{
"@id": "/private/bots/charlie/SKILL.md",
"skill:format": "anthropic.skill.v1",
"skill:scope": ["read_resource", "write_resource", "subscribe"],
"schema:name": "Charlie"
}
```
New formats (`openai.tool.v1`, `w3c.future.skill.v2`, …) plug in by declaring a new `skill:format` value. Existing bots that don't recognise a format skip it gracefully. The discovery channel stays stable; the payload evolves.
New MCP tools (first-class, sit alongside CRUD)
Crucially, these are additions on top of regular `read_resource` — a bot that doesn't speak the skill vocabulary can still find SKILL.md via plain CRUD. But for skill-aware bots, the dedicated tools give a typed, structured way in.
Optional index for performance (`.well-known/skills.jsonld`)
Walking conventions on every `list_skills` call is fine at small scale. If a pod has hundreds of skills, the MCP server can opportunistically cache results in `/.well-known/skills.jsonld` — a JSON-LD index of every skill on the pod. Same data, faster lookup. The format:
```json
{
"@context": { "skill": "urn:skill:", "schema": "https://schema.org/" },
"@type": "skill:SkillIndex",
"skill:items": [ /* … */ ]
}
```
This is an optimisation, not a requirement. Bots use `list_skills` and don't care which path the server took to answer.
What this gives us
Tool count update
Adding skills to the surface brings the total to ~20 tools across CRUD / ACL / discovery / docs / skills / subscribe / federation. Still a single-PR sized substrate.
feat: MCP server — pod as a tool surface for agents (closes #490) (#491)
melvincarvalho commented on May 18, 2026
v0.0.200 shipped the substrate. Three follow-up issues filed for the Tier-2 gaps surfaced by the live-fire smoke (the "hour with jspod --mcp" journo session):
All three are MCP-server-level features and live in this repo. The jspod/nosdav-server wrappers just need flag passthrough when JSS gains the next set of MCP-related flags (none anticipated for these three — they're new tools, not new server flags).
feat(mcp): subscribe, read_acl/write_acl, call_remote_pod (closes #494 …