Agent connections

The kit serves two remote MCP servers, one per deployable app. The web app's Express process serves the User MCP next to the website; the admin app's Express process serves the Admin MCP next to the administration UI. Users connect agents to one workspace through the User MCP; application administrators connect through the Admin MCP. Both are read-only in v5. For the shared concepts and the client-side flow, see user and admin MCPs and connect an agent.

Where users manage connections

The repository's docs/admin-app.md maps each kit's admin deployment to <subdomain>-admin.usenextbase.com, which gives the admin address above for the demo. The product navigation has an Agent connections entry and the account settings page links to it. Administrators see Admin agent connections in the admin app's navigation. Each page shows the server address to copy, the list of connected agents with their workspace and scope, and a Disconnect button per connection. The UI limits active connections to 20 per account.

Your own deployments use each app's APP_URL as the origin, so the servers are ${APP_URL of web}/mcp/user and ${APP_URL of admin}/mcp/admin. The settings pages print the exact address. Each app advertises and authorizes only its own audience: apps/web/src/mcp/adapter.ts sets audiences: ["user"] and apps/admin/src/mcp/adapter.ts sets audiences: ["admin"], so a request for /mcp/admin on the web origin (or /mcp/user on the admin origin) is rejected with invalid_target.

Tools and permissions

Every tool is registered with readOnlyHint: true and destructiveHint: false. There are no write tools, and the scopes do not grant writes. A user token never lists or calls admin tools, and an admin token is rejected at /mcp/user.

Each tool call re-authenticates the bearer token and reloads the live actor through public.mcp_live_actor, which requires an existing auth.sessions row, a confirmed email, no active ban and a session that has not expired. projects_list runs public.mcp_projects, which checks membership and the view_projects permission in the same SQL statement as the read. Admin tools additionally require a current admin row in public.user_roles.

Consent and OAuth behaviour

The agent needs to support Streamable HTTP, OAuth with public dynamic client registration and PKCE S256. The steps below apply to each app on its own origin.

1. The client discovers the server through /.well-known/oauth-protected-resource/mcp/user (web) or /.well-known/oauth-protected-resource/mcp/admin (admin). The authorization server issuer is ${APP_URL}/oauth with metadata at /.well-known/oauth-authorization-server/oauth.
2. The client registers at /oauth/register and starts authorization at /oauth/authorize, which redirects to the consent page /mcp/authorize?request_id=....
3. If you are not signed in, the app sends you to /login?next=/mcp/authorize?... and returns you to the same request afterwards.
4. The consent page shows the client's self-reported name (marked unverified), the callback address, the server, the scope with "Read access only" and your email. For a user connection you select one workspace; only workspaces where you are owner, admin or have view_projects are offered. Approve with Allow read access or Cancel.
5. The client exchanges the code at /oauth/token. Revocation is /oauth/revoke.

Lifetimes: pending consent 10 minutes, authorization codes 5 minutes, access tokens 15 minutes, refresh for at most 30 days and never beyond the original sign-in session. Refresh tokens rotate; reuse revokes the whole connection family. Secrets are stored only as SHA-256 hashes. Callback URLs must be HTTPS, except HTTP loopback addresses. Browser clients are accepted from the app's APP_URL, https://claude.ai and https://chatgpt.com; desktop and server clients without an Origin header are accepted too. Confidential clients and client ID metadata documents are not supported.

Access ends when you disconnect, sign out of the session that approved the connection, lose workspace access or lose the administrator role. If an agent starts getting 401, sign in again and reconnect.

Where the code lives

The MCP module is the same code in both apps; only adapter.ts differs (the audiences setting). Paths below are for apps/web; apps/admin/src/mcp/ has the same files minus the tests.

Do not add React Router routes under /mcp/, /oauth/ or /.well-known/oauth-* in either app; Express handles them first.

Adding a tool safely

Follow the mcp-tool skill in the repository. In short:

1. Extend the Adapter interface in core.ts and register the tool inside the matching audience branch (audience === "user" or the else branch). Reuse the shared annotations and limitSchema; validate any other input with Zod and bound strings with .max(...).
2. Inside the handler always call await currentActor() and, for user tools, pass auth.grant.workspace. Never accept a workspace id from tool input and never reuse an actor captured earlier.
3. Implement the data access in supabase-adapter.ts. User tools should call a new service-only SQL function modelled on public.mcp_projects that checks mcp_live_actor and membership in the same statement. Admin tools re-check (await liveActor(actor))?.admin before a bounded select of explicit columns. Create the function in a new migration; never edit the shipped MCP migration. Then run pnpm gen-types-local.
4. Mirror the change into the other app's src/mcp/ so the two copies stay identical (user tools only matter in the web app and admin tools only in the admin app, but the shared core.ts should not diverge).
5. Add tests in apps/web/src/mcp/core.test.ts: update the exact tool-name lists, add a call test, a bounds test and a cross-audience test. Add a pgTAP test asserting anon and authenticated cannot execute the new function.
6. Update the tool table in docs/mcp-connections.md.

pnpm --filter web exec vitest run src/mcp/core.test.ts
pnpm typecheck && pnpm lint
pnpm test-db

Adding a write tool needs a new scope and new consent copy first. The consent screen currently says "Read access only", and the repository's AGENTS.md lists adding write capability without that design as something to never do.