Solid Pod MCP Server (TypeScript / SSE)

This project provides a Model Context Protocol (MCP) server for Solid Pods. It exposes CRUD-style tools that can read, write, and delete Pod resources using Solid authentication and agent-specific identities.

The server uses Server-Sent Events (SSE) for the MCP transport and is intended for local development and testing.

Project structure

• src/index.ts: HTTP server, admin endpoints, SSE lifecycle and session routing.
• src/mcp/createServer.ts: MCP server and tool registrations (read/write/delete/profile tools).
• src/lib/auth.ts: Agent registry, inrupt Session management, and auth helpers.
• src/lib/logger.ts: Centralized logging to mcp-server.log and stderr.

What You Need

To run the server and test it with Postman, you need the following credentials and values:

• MCP_ADMIN_TOKEN: required for all admin endpoints such as /admin/login, /admin/agents, /admin/session, and /admin/session/active
• Solid OAuth client credentials for each agent:
  • clientId
  • clientSecret
  • oidcIssuer
• The agent WebID that is written into the Pod ACL files
• The MCP sessionId returned by the /sse endpoint
• The local server URL, usually http://localhost:3000

The agent credentials are used to log in against the Solid issuer. The Pod ACLs then decide whether the authenticated agent WebID may access the resource.

For demo purposes, you can log in the startup admin session automatically from .env, log in additional agents through Postman, and then select which session Claude Desktop should use.

Setup

1. Install dependencies

npm install

2. Configure the environment

Create a .env file or update the existing one with at least the admin token:

MCP_ADMIN_TOKEN=your_admin_token

If you want to log in agents through the admin API, make sure you have the Solid OAuth client credentials for each agent ready.

For the automatically logged-in startup admin session, set these variables:

• ADMIN_SESSION_LABEL
• ADMIN_SESSION_CLIENT_ID
• ADMIN_SESSION_CLIENT_SECRET
• ADMIN_SESSION_OIDC_ISSUER

3. Build and start the server

npm start

The server listens on http://0.0.0.0:3000/sse by default.

Using the MCP Server

Testing with Claude Desktop

If you want to use Claude Desktop for the actual interaction, select the session you want first and then use Claude normally without an agentId in the tool arguments.

The server uses the currently selected session when no agentId is included in an MCP message. By default, this is the startup admin session from the ADMIN_SESSION_* variables in .env.

We recommend using e.g. ngrok to tunnel your locally hosted server over HTTPS, since Claude Desktop does not allow HTTP MCP connections.

Minimal workflow for using Claude Desktop with a chosen session:

1. Make sure the startup admin session is configured in .env.
2. Optionally, log in an additional agent through /admin/login.
3. Optionally, select the session you want Claude to use via POST /admin/session/active. (see options below)
4. Connect Claude Desktop to /sse and use it normally.

In Postman, the collection includes ready-made requests for:

• POST /admin/session/active with { "scope": "admin" }
• POST /admin/session/active with { "scope": "agent", "agentId": "agent-1" }
• POST /admin/session/active with { "scope": "unauthenticated" }

Testing with Postman

Use the collection file MCP Solid Multi-Agent Testing.postman_collection.json.

Import the collection

In Postman, import the collection file from the repository root and set up a local environment with these variables:

• baseUrl = http://localhost:3000
• adminToken = your MCP_ADMIN_TOKEN
• sessionId = the ID returned by /sse
• oidcIssuer = the Solid issuer URL used by your agents
• agent1ClientId / agent1ClientSecret
• agent2ClientId / agent2ClientSecret if you test with a second agent identity
• agent1WebId and agent2WebId matching the WebIDs written into the ACL files
• podUri = the base Pod URL you want to test

Recommended test order

1. Open Setup & Admin.
2. Run Register Agent1 and, if needed, Register Agent2.
3. Run the matching Agent Login request for each agent.
4. Open Initialize MCP Connection and keep the SSE request open.
5. Copy the sessionId from the SSE response into the Postman environment.
6. Run the tool calls under MCP - Tool Calls (Agent Identity).
7. Use the Test Scenarios section to verify e.g. denied access.

If Postman shows 202 Accepted, that is expected. The MCP response is delivered through the initial SSE connection. Have a look in the respective tab.