---
title: "How it works"
description: "past.dev validates who you are, works out what you're allowed to do from its own records, and shows your assistant only the tools that survive that check."
canonical: https://past.dev/docs/mcp/how-it-works
last-updated: 2026-08-26
---
# How it works

> past.dev validates who you are, works out what you're allowed to do from its own records, and shows your assistant only the tools that survive that check.

Product: past.dev MCP Server. Source: https://past.dev/docs/mcp/how-it-works

### Signing in

past.dev's MCP server issues no credentials of its own. Sign-in is handled by **WorkOS AuthKit** at `sso.past.dev`, the same identity service behind the past.dev app. The server's only job is to check the resulting token and decide what it permits.

The whole exchange is automatic, and it's why you never paste a key:

1. **Your client asks the server who it answers to** It fetches `/.well-known/oauth-protected-resource` and learns the sign-in service is `sso.past.dev`. This is the standard discovery document defined by RFC 9728.
2. **Your client registers itself** Dynamic Client Registration means the client obtains its own identity on the fly. Nothing is shared between users, and nothing was pre-provisioned by an administrator.
3. **You sign in and consent, in a real browser** Standard authorization code flow with PKCE (S256 required). Your password is entered on past.dev's own sign-in page and is never seen by the AI client.
4. **The client receives a short-lived access token** Bound by audience to `https://api.past.dev/mcp`, so it is useless anywhere else, including against past.dev's other APIs. A refresh token keeps the connection alive without asking you again.
5. **Every subsequent request carries that token** And every one of them is re-validated from scratch. See below.

### What happens on each request

There is no trusted session sitting in memory. Each call your assistant makes runs the full check:

| Step | What is checked |
| --- | --- |
| **Validate the token** | RS256 signature against past.dev's published JWKS keys, plus issuer, audience and expiry, with 30 seconds of clock tolerance. Anything wrong returns `401` with a pointer back to the discovery document, so the client knows to re-authenticate rather than guess. |
| **Resolve who you are** | The token carries an opaque user identifier and nothing else: no email, no role, no permissions. past.dev maps it to a user record in its own database. |
| **Confirm you still belong** | Your active membership of your current workspace is re-checked. Removed from the workspace? The very next call fails, whether or not your token has expired. |
| **Compute your permissions** | From your workspace role in past.dev's database, never from anything the token claims. |
| **Filter the tool list** | Tools whose required permission you don't hold are removed before your assistant ever sees them. |

Because this runs per request rather than per session, a role change or an offboarding takes effect immediately. There is no stale session to wait out.

### Permissions, concretely

Every tool declares one required permission, written `domain:action`. The two tools on this page need two of them, and every workspace role, Member included, grants both.

| Tool | Required permission |
| --- | --- |
| `list_my_memories` | `memories:read` |
| `add_memory` | `memories:write` |

The check **fails closed** by design. A tool with no declared permission is never exposed to anyone; a request with no resolvable user gets an empty tool list rather than a default one. Adding a tool without also granting its permission makes it invisible, not accidentally public.

### Where the server runs

past.dev's MCP server runs inside the main past.dev API, behind the same TLS termination, edge protection and infrastructure as the product. It runs *stateless*: no conversation state is retained between calls, requests can be served by any instance, and session identifiers handed back to clients are encrypted rather than guessable. That is what makes the per-request revalidation above possible, and it means a deploy or restart never silently downgrades a live connection.