Plurality MCP Server

Universal memory for AI agents and tools. Save, organize and search context anywhere.

An Model Context Protocol server that gives any MCP-compatible AI client persistent memory — documents, notes, conversations, and files stored across organized memory buckets with semantic search. Supports OAuth and Personal Access Tokens (PAT) based authentication.

Why use this?

• Memory Studio — a personal knowledge base and second brain where you organize context into memory buckets, review saved content, and manage what your AI agents know.
• Save important chats — directly from within Claude, ChatGPT, Cursor, and other AI tools into the relevant memory bucket
• Shared persistent memory across all your agents — Claude Code, Lovable, Cursor, OpenClaw and more all access the same context
• Semantic search — find relevant memories using natural language, not just keywords
• Share buckets with other people — collaborate by giving others access to your context
• Works everywhere — any MCP-compatible client can connect

We also have a Chrome extension called AI Context Flow that lets you capture and use context on any website. It comes with a built-in chat agent (30+ models) that opens as a sidebar on any page — talk to your memories, answer questions from your stored context, and surface connections across everything you've saved. You can use the MCP Server alongside the extension to get full feature set of the product.

📖 Full documentation · 🌐 Website · 🧩 Chrome Extension · 🧠 Memory Studio

Quick connect (production)

Production URL: `https://app.plurality.network/mcp`

The server supports OAuth 2.1 with PKCE (for interactive clients) and Personal Access Tokens (for headless agents and CI). Most clients handle the OAuth flow automatically.

Works with Claude Desktop, Claude Code, ChatGPT, Cursor, and any MCP-compatible client.

→ **Step-by-step setup guides for all supported clients**

Tools

Authentication

The MCP server accepts two auth methods:

Using a Personal Access Token

1. Sign in to the dashboard, open Connect via MCP → Manage tokens

2. Click Create token, give it a name and optional expiry, copy the `plur_pat_…` value

3. Configure your client to send it as a Bearer token:

Authorization: Bearer plur_pat_...

PATs require a paid plan. They auto-revoke at expiry, can be rotated with a configurable grace period (default 7 days), and can be immediately revoked from the dashboard. They are stored hashed and never appear in logs.

OAuth details

The server uses Ory Hydra as the OAuth2/OIDC provider:

OAuth2 flow (step by step)

1. Client discovers auth server — fetches `/.well-known/oauth-protected-resource` from Traefik

2. Client registers — calls `/register` (Dynamic Client Registration) to get `client_id`/`client_secret`. The API Gateway proxies this to Hydra, injecting the `mcp:tools` scope

3. User authenticates — browser opens Hydra's login flow, which redirects to the frontend's login/consent pages

4. Token issued — Hydra returns a JWT access token (RS256, 15min TTL) with the user's ID as the `sub` claim and `mcp:tools` scope

5. Authenticated requests — client includes `Authorization: Bearer ` on all MCP requests

6. MCP server validates — JWT signature verified locally against Hydra's JWKS public keys (cached 1 hour), `mcp:tools` scope is checked

7. API Gateway access — MCP server forwards the Bearer token when calling API Gateway endpoints for data retrieval and storage

Architecture

MCP Client (Claude Code, Cursor, etc.)
    │
    │  OAuth2 + Streamable HTTP
    ▼
Traefik (:5050)           ← single entrypoint for clients
    ├── /mcp              → MCP Server (:5051)
    ├── /.well-known/*    → API Gateway or Hydra
    ├── /oauth2/*         → Hydra (:4444)
    └── /register         → API Gateway (DCR proxy)
                                │
                                │ Bearer token
                                ▼
                          API Gateway (:5000)
                                │
                                ▼
                          Vector Service (:8000)

Traefik is the single entrypoint. It routes OAuth traffic to Hydra and MCP protocol traffic to the MCP server. The MCP server validates JWTs locally via Hydra's JWKS keys, then forwards the Bearer token to the API Gateway for data access. The API Gateway handles authentication, DCR proxying, and routes vector/search operations to the Vector Service.

Local development setup

Prerequisites

• Python 3.11+
• uv (Python package manager)
• Docker and Docker Compose
• Running API Gateway (plurality-backend-api): Handles authentication, OAuth metadata, DCR proxying, and database access
• Running Vector Service (plurality-ai-service): Handles semantic search and vector database operations

1. Install dependencies

cd plurality-mcp-server
pip install uv
uv sync

2. Configure environment

cp .env.example .env

Default values work for local development — no changes needed if the API Gateway runs on `:5000`:

HYDRA_ISSUER=http://localhost:5050
MCP_RESOURCE_URL=http://localhost:5050
BACKEND_API_URL=http://localhost:5000

3. Start Docker services (Hydra + Traefik)

cd ory-hydra
docker compose up -d

This starts:

Wait for services to be healthy: `docker compose ps`

4. Start the MCP server

uv run uvicorn main:mcp_server --host 0.0.0.0 --port 5051 --reload

> Port 5051, not 5050. Traefik listens on 5050 and proxies `/mcp` to the MCP server on 5051.

5. Verify

# Health check (direct)
curl http://localhost:5051/mcp/health

# OAuth metadata (via Traefik)
curl http://localhost:5050/.well-known/oauth-protected-resource

# Traefik dashboard (for debugging routes)
open http://localhost:8080

Local client configuration

Claude Code

claude mcp add --transport http plurality-memory http://localhost:5050/mcp

Then authenticate via `/mcp` inside Claude Code.

Claude Code — VS Code Extension

Authenticate first in the terminal using the steps above. Then add `.mcp.json` to your project root:

{
  "mcpServers": {
    "plurality-memory": {
      "type": "http",
      "url": "http://localhost:5050/mcp"
    }
  }
}

> The VS Code extension may not trigger the OAuth browser flow automatically. Complete authentication via the terminal first.

Claude Desktop

Edit your config file:

• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
• Windows: `%APPDATA%\Claude\claude_desktop_config.json`

{
  "mcpServers": {
    "plurality-memory": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:5050/mcp"]
    }
  }
}

Restart Claude Desktop fully, then authenticate when the browser opens.

MCP Inspector (debugging)

npx @modelcontextprotocol/inspector

Enter `http://localhost:5050/mcp` as the server URL. The inspector walks through the OAuth flow and lets you call tools interactively.

> Note: ChatGPT is not supported for local development — it requires publicly reachable OAuth endpoints.

Project structure

plurality-mcp-server/
├── main.py                             # Entry point
├── pyproject.toml                      # Dependencies (managed by uv)
├── .env.example                        # Environment template
├── src/plurality_mcp_server/
│   ├── app.py                          # FastMCP app + middleware stack
│   ├── config.py                       # Env vars, shared HTTP client, context vars
│   ├── auth.py                         # JWT validation via Hydra JWKS + scope check
│   └── tools.py                        # MCP tool definitions (read + write)
└── ory-hydra/
    ├── docker-compose.yml              # Hydra + Traefik + PostgreSQL
    ├── hydra.yml                       # Hydra OAuth2/OIDC config
    ├── traefik.yml                     # Traefik static config
    └── dynamic.yml                     # Traefik routing rules

Troubleshooting

MCP client gets 401 Unauthorized

• Check that Hydra is running: `curl http://localhost:4444/.well-known/openid-configuration`
• Check that the JWT hasn't expired (15min TTL)
• Verify `HYDRA_ISSUER` matches the issuer in the token's `iss` claim
• Ensure the token has the `mcp:tools` scope

MCP client gets 502 Bad Gateway

• The MCP server isn't running on port 5051
• Check Traefik logs: `docker compose -f ory-hydra/docker-compose.yml logs traefik`

Tools return "Error: Backend API returned status 401"

• The API Gateway needs to accept Hydra JWTs — ensure `jwks-rsa` is installed and the OAuth auth middleware is deployed

OAuth flow redirects to localhost:3000 but nothing is there

• Hydra is configured with `login: http://localhost:3000/login` — this points to the Plurality frontend. Start the frontend or update `hydra.yml` URLs.

DCR returns unexpected scope or missing mcp:tools

• The API Gateway's DCR proxy injects `mcp:tools` into the allowed scopes. Ensure the API Gateway is running and the `/register` route is reachable.

Links

• 📖 Documentation
• 🌐 Website
• 🧩 Chrome Extension
• 🧠 Memory Studio
• 📦 MCP Registry
• 🔧 Smithery