\n \n $\"Watch$ \n \n

▶️ Watch the demo

\n\n\n📖 [Full documentation](https://docs.plurality.network/the-plurality-mcp-server) · 🌐 [Website](https://plurality.network/ai-context-flow) · 🧩 [Chrome Extension](https://chromewebstore.google.com/detail/ai-context-flow-use-your/cfegfckldnmbdnimjgfamhjnmjpcmgnf) · 🧠 [Memory Studio](https://app.plurality.network)\n\n---\n\n## Quick connect (production)\n\nProduction URL: `https://app.plurality.network/mcp`\n\nThe 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.\n\nWorks with Claude Desktop, Claude Code, ChatGPT, Cursor, and any MCP-compatible client.\n\n→ **[Step-by-step setup guides for all supported clients](https://docs.plurality.network/the-plurality-mcp-server/connect-your-agents-via-mcp)**\n\n---\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_user_memory_buckets` | List all memory buckets (organized folders) for the user |\n| `list_items_in_memory_bucket` | List stored items in a specific bucket (metadata only) |\n| `search_memory` | Semantic search across buckets with relevance scoring |\n| `read_context` | Read the full content of a stored item with pagination |\n| `save_memory` | Save text content to a specific memory bucket |\n| `save_conversation` | Save a conversation (chat history) to a memory bucket |\n| `create_memory_bucket` | Create a new memory bucket for organizing saved content |\n\n---\n\n## Authentication\n\nThe MCP server accepts two auth methods:\n\n| Method | When to use | Browser required? |\n|--------|-------------|-------------------|\n| **OAuth 2.1 + PKCE** | Interactive clients: Claude Desktop, Web, Code, ChatGPT | Yes (one-time) |\n| **Personal Access Token (PAT)** | Headless agents, CI runners, custom integrations, n8n, LangChain | No |\n\n### Using a Personal Access Token\n\n1. Sign in to the [dashboard](https://app.plurality.network), open **Connect via MCP → Manage tokens**\n2. Click **Create token**, give it a name and optional expiry, copy the `plur_pat_…` value\n3. Configure your client to send it as a Bearer token:\n\n```\nAuthorization: Bearer plur_pat_...\n```\n\nPATs 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.\n\n### OAuth details\n\nThe server uses [Ory Hydra](https://www.ory.sh/hydra/) as the OAuth2/OIDC provider:\n\n| Property | Value |\n|----------|-------|\n| Algorithm | RS256 |\n| Issuer | `https://app.plurality.network` (prod) |\n| Scope | `openid offline_access mcp:tools` |\n| Access token TTL | 15 minutes |\n| Refresh token TTL | 720 hours |\n| Discovery | `https://app.plurality.network/.well-known/oauth-authorization-server` |\n| Dynamic Client Registration | `https://app.plurality.network/register` |\n\n

OAuth2 flow (step by step)

\n\n1. **Client discovers auth server** — fetches `/.well-known/oauth-protected-resource` from Traefik\n2. **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\n3. **User authenticates** — browser opens Hydra's login flow, which redirects to the frontend's login/consent pages\n4. **Token issued** — Hydra returns a JWT access token (RS256, 15min TTL) with the user's ID as the `sub` claim and `mcp:tools` scope\n5. **Authenticated requests** — client includes `Authorization: Bearer ` on all MCP requests\n6. **MCP server validates** — JWT signature verified locally against Hydra's JWKS public keys (cached 1 hour), `mcp:tools` scope is checked\n7. **API Gateway access** — MCP server forwards the Bearer token when calling API Gateway endpoints for data retrieval and storage\n\n

\n\n---\n\n## Architecture\n\n```\nMCP Client (Claude Code, Cursor, etc.)\n │\n │ OAuth2 + Streamable HTTP\n ▼\nTraefik (:5050) ← single entrypoint for clients\n ├── /mcp → MCP Server (:5051)\n ├── /.well-known/* → API Gateway or Hydra\n ├── /oauth2/* → Hydra (:4444)\n └── /register → API Gateway (DCR proxy)\n │\n │ Bearer token\n ▼\n API Gateway (:5000)\n │\n ▼\n Vector Service (:8000)\n```\n\n**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.\n\n---\n\n## Local development setup\n\n### Prerequisites\n\n- Python 3.11+\n- [uv](https://docs.astral.sh/uv/) (Python package manager)\n- Docker and Docker Compose\n- Running **API Gateway** (plurality-backend-api): Handles authentication, OAuth metadata, DCR proxying, and database access\n- Running **Vector Service** (plurality-ai-service): Handles semantic search and vector database operations\n\n### 1. Install dependencies\n\n```bash\ncd plurality-mcp-server\npip install uv\nuv sync\n```\n\n### 2. Configure environment\n\n```bash\ncp .env.example .env\n```\n\nDefault values work for local development — no changes needed if the API Gateway runs on `:5000`:\n\n```\nHYDRA_ISSUER=http://localhost:5050\nMCP_RESOURCE_URL=http://localhost:5050\nBACKEND_API_URL=http://localhost:5000\n```\n\n### 3. Start Docker services (Hydra + Traefik)\n\n```bash\ncd ory-hydra\ndocker compose up -d\n```\n\nThis starts:\n\n| Service | Port | Purpose |\n|---------|------|---------|\n| **PostgreSQL** | 5433 | Hydra's database |\n| **Hydra** | 4444, 4445 | OAuth2/OIDC provider (public + admin) |\n| **Traefik** | 5050 | Reverse proxy / routing |\n\nWait for services to be healthy: `docker compose ps`\n\n### 4. Start the MCP server\n\n```bash\nuv run uvicorn main:mcp_server --host 0.0.0.0 --port 5051 --reload\n```\n\n> **Port 5051**, not 5050. Traefik listens on 5050 and proxies `/mcp` to the MCP server on 5051.\n\n### 5. Verify\n\n```bash\n# Health check (direct)\ncurl http://localhost:5051/mcp/health\n\n# OAuth metadata (via Traefik)\ncurl http://localhost:5050/.well-known/oauth-protected-resource\n\n# Traefik dashboard (for debugging routes)\nopen http://localhost:8080\n```\n\n### Local client configuration\n\n

Claude Code

\n\n```bash\nclaude mcp add --transport http plurality-memory http://localhost:5050/mcp\n```\n\nThen authenticate via `/mcp` inside Claude Code.\n\n

\n\n

Claude Code — VS Code Extension

\n\nAuthenticate first in the terminal using the steps above. Then add `.mcp.json` to your project root:\n\n```json\n{\n \"mcpServers\": {\n \"plurality-memory\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:5050/mcp\"\n }\n }\n}\n```\n\n> The VS Code extension may not trigger the OAuth browser flow automatically. Complete authentication via the terminal first.\n\n

\n\n

Claude Desktop

\n\nEdit your config file:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"plurality-memory\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"http://localhost:5050/mcp\"]\n }\n }\n}\n```\n\nRestart Claude Desktop fully, then authenticate when the browser opens.\n\n

\n\n

MCP Inspector (debugging)

\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\nEnter `http://localhost:5050/mcp` as the server URL. The inspector walks through the OAuth flow and lets you call tools interactively.\n\n

\n\n> **Note:** ChatGPT is not supported for local development — it requires publicly reachable OAuth endpoints.\n\n---\n\n## Project structure\n\n```\nplurality-mcp-server/\n├── main.py # Entry point\n├── pyproject.toml # Dependencies (managed by uv)\n├── .env.example # Environment template\n├── src/plurality_mcp_server/\n│ ├── app.py # FastMCP app + middleware stack\n│ ├── config.py # Env vars, shared HTTP client, context vars\n│ ├── auth.py # JWT validation via Hydra JWKS + scope check\n│ └── tools.py # MCP tool definitions (read + write)\n└── ory-hydra/\n ├── docker-compose.yml # Hydra + Traefik + PostgreSQL\n ├── hydra.yml # Hydra OAuth2/OIDC config\n ├── traefik.yml # Traefik static config\n └── dynamic.yml # Traefik routing rules\n```\n\n---\n\n## Troubleshooting\n\n

MCP client gets 401 Unauthorized

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

\n\n

MCP client gets 502 Bad Gateway

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

\n\n

Tools return \"Error: Backend API returned status 401\"

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

\n\n

OAuth flow redirects to localhost:3000 but nothing is there

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

\n\n

DCR returns unexpected scope or missing mcp:tools

\n\n- 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.\n\n

\n\n---\n\n## Links\n\n- 📖 [Documentation](https://docs.plurality.network/the-plurality-mcp-server)\n- 🌐 [Website](https://plurality.network)\n- 🧩 [Chrome Extension](https://chromewebstore.google.com/detail/ai-context-flow-use-your/cfegfckldnmbdnimjgfamhjnmjpcmgnf)\n- 🧠 [Memory Studio](https://app.plurality.network)\n- 📦 [MCP Registry](https://registry.modelcontextprotocol.io/?q=ai-context-flow)\n- 🔧 [Smithery](https://smithery.ai/servers/plurality-network/ai-context-flow)\n\n---\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_103":104,"_105":-5,"_106":107,"_108":109,"_110":111,"_112":113},"requiredSecrets",[],"tags",[101,102],"assets",[],"stats",{"_99":86,"_100":86},"ratingAvg","reviewCount","ai-knowledge","ai-memory","topics",[101,102],"license","language","Python","registryName","network.plurality/ai-context-flow","homepage","https://plurality.network/ai-context-flow","packages",[],"ENV",{"_116":117,"_118":119,"_120":121},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

AI Context Flow