---
title: "How it works"
description: "Both servers verify identity and permissions on every request. The client receives only the tools the caller holds at that moment."
canonical: https://past.dev/docs/mcp/how-it-works
last-updated: 2026-10-09
---
# How it works

> Both servers verify identity and permissions on every request. The client receives only the tools the caller holds at that moment.

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

### Signing in to the account server

On past.dev's cloud, sign-in uses **WorkOS AuthKit** at `sso.past.dev`, the same identity service the console uses.

The client completes these steps itself:

1. **Discover the authorization server** The client opens the endpoint with no credential and receives `401` with a `WWW-Authenticate` challenge carrying `resource_metadata`. RFC 9728 metadata names the authorization server, and RFC 8414 metadata for that server is served at the resource origin as well, so a client that knows only the MCP URL completes the flow.
2. **Register the client** Dynamic Client Registration assigns an identity to the client, so no administrator provisions it in advance. Redirect URIs are exact-match and must be HTTPS or loopback.
3. **Sign in and approve access** The browser runs the authorization code flow with PKCE. S256 is required. You enter your password on past.dev's own sign-in page. The AI client never receives it.
4. **Receive a short-lived access token** The audience binds the token to the MCP address it was issued for. It reaches no other past.dev API, and a token issued for another address is refused. A refresh token renews the connection without another sign-in.
5. **Send the token with each request** The server validates the token and recomputes the caller's permissions for every request.

### What happens on each request

The transport is stateless. The server keeps no authorization session between calls, and performs these checks every time:

| Step | What is checked |
| --- | --- |
| **Validate the token** | The signature is verified against the published JWKS keys, along with issuer, audience and expiry. A failed check returns `401` with a reference to the discovery document, so the client can authenticate again. |
| **Resolve who you are** | The token carries an opaque identifier and no email, role or permission. The server maps the identifier to a record in its own database. |
| **Confirm you still belong** | The account server verifies an accepted organization membership. After a removal the next call fails, however long the token still has to live. A pending invitation to the same address does not reopen an old token. |
| **Compute your permissions** | Permissions come from the platform role and the project reach held in the database. Permission claims inside a token are never used. |
| **Filter the tool list** | A tool whose scope the caller lacks is removed from the list. Because the list is derived per request, a role change appears on the assistant's next tool listing with no reconnect. |

### Tool permissions

Each account tool carries one scope. The scope table maps each platform role to the scopes it holds. Holding a scope allows a family of tools at all; reach inside a project is still resolved on every call, so a Member holding the project scope administers only the projects they reach, at the level each tool needs.

Authorization **fails closed**. A tool without a declared scope is never exposed. A request with no resolved caller receives an empty tool list. A new tool stays unavailable until a role holds its scope.

### What the server tells the assistant

The account server's handshake carries instructions: that every action runs as the signed-in person, that an absent tool means a missing permission to report rather than work around, that destructive tools ask for `confirm`, and that slugs and ids are used exactly as another tool returned them. Each tool description names the console screen it mirrors and the role it needs, so an assistant can explain a refusal in the words you will find on the screen.

### Rate limits

The account server carries one rate budget per person, shared by every token and every client that person connected. It counts every request, including tool listings and the handshake. Past the budget a request answers `429` with `Retry-After` and leaves no record. A request with no valid token is answered `401`, never `429`, because the budget belongs to the person a token names.

### Where the server runs

Both servers run inside the main past.dev API, behind the same TLS termination, network protection and infrastructure. Neither retains conversation state between calls, so any instance can serve any request. Deployments and restarts do not change a connection's security settings.