For developers
Build an app for the hub.
uffda is a small hub of apps made for friends. Plug your app in and everyone on the hub signs in with one button, and they can use your app from Claude through one connection.
Point at a button, or tab to it, and it winks.
What uffda is.
uffdahub.com is home to a few little apps that friends built for each other, starting with even for splitting bills. People sign in to the hub once with Google and see the apps that are shared with them. Your app can join in three ways.
One sign-in
The hub is an OpenID Connect provider. Someone already signed in at the hub comes straight back to your app signed in.
The button
A Sign in with uffda button in plain HTML and CSS, with a little wink. No JavaScript, no tracking.
Claude
People connect Claude to uffdahub.com/mcp once, and your app's tools show up for everyone who can use your app.
- Your appSign in with uffda
/oidc/authorize- uffda hubGoogle, once. Is the app shared with them?
?code=then/oidc/token- Your appChecks the ID token, starts a session
- ClaudeOne connector for every app
uffdahub.com/mcp- uffda hubOnly tools this person may use
- hub pass, 60 s
- Your appYour
/mcp, acting as that person
Sign in with uffda.
The hub speaks standard OpenID Connect: the code flow with PKCE, ES256-signed ID tokens, a private id for each person in each app, and back-channel sign-out. Any OIDC library works. The examples below use plain fetch and the jose library for checking tokens, and even's src/uffda.js is a full version with no libraries at all.
Set up your app
List your app on the hub
Sign in at uffdahub.com, open Your apps and choose List an app. Give it a name, a web address, an icon and a few screenshots, and choose who can see it: only you, certain people, or everyone on the hub.
Ask for sign-in
A hub admin turns on Sign in with uffda from your app's edit page. Email dev@runflip.com with your app's name and these:
- Return addresses: your callback, exactly, like
https://yourapp.example/auth/uffda/callback. Up to 10. https only, excepthttp://localhostfor testing. - Sign-out address (optional): where the hub posts a logout token when someone signs out of the hub.
- Open sign-up (rare): whether anyone with a Google account may join the hub by signing in to your app. Leave it off unless your app is public, like even.
- Return addresses: your callback, exactly, like
Keep the secret secret
The hub shows the client id and client secret once. Put both in your app's secrets (even uses
UFFDA_CLIENT_IDandUFFDA_CLIENT_SECRET). The hub keeps only a hash of the secret, so a lost secret can't be shown again: an admin makes a new one, and the old one stops working straight away.
Endpoints
Everything is listed at /.well-known/openid-configuration.
| Endpoint | What it does |
|---|---|
GET /.well-known/openid-configuration | Discovery |
GET /.well-known/jwks.json | The hub's public signing keys (ES256). Cache them; fetch again for a kid you haven't seen. |
GET /oidc/authorize | Starts sign-in. Code flow, PKCE with S256 required. |
POST /oidc/token | Swaps a code or refresh token for tokens. Client secret by HTTP Basic or in the form. |
GET /oidc/userinfo | Who an access token belongs to, with Authorization: Bearer. |
GET /oidc/logout | Signed out of your app; the hub offers to sign out of the hub too. |
POST /oidc/claude-off | For a Disconnect button in your app: switches your app off for that person’s Claude. Client secret by HTTP Basic, and sub in the form. They turn it back on from their hub account. |
| Scope | What your app gets |
|---|---|
openid | sub: a private id for this person in your app. Different in every app, and it never changes. |
email | email and email_verified (always true: the hub only has Google-verified addresses). |
profile | name and, when they have one, picture (their Google photo). |
offline_access | A refresh token, so you can check once a day that they can still use your app. |
The flow
Send them to the hub
Make a PKCE verifier, a
stateand anonce, keep them for the callback, and redirect. Addprompt=noneto check quietly: someone signed in at the hub comes straight back with a code, anyone else comes back witherror=login_requiredand you show your own sign-in page.src/signin.jsjs // GET /auth/uffda on your app: send the person to the hub. const HUB = 'https://uffdahub.com'; const RETURN = 'https://yourapp.example/auth/uffda/callback'; // exactly as registered const b64u = (bytes) => btoa(String.fromCharCode(...bytes)) .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); const random = () => b64u(crypto.getRandomValues(new Uint8Array(32))); export async function startSignIn(env) { const verifier = random(), state = random(), nonce = random(); const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)); const url = new URL(`${HUB}/oidc/authorize`); url.search = new URLSearchParams({ response_type: 'code', client_id: env.UFFDA_CLIENT_ID, redirect_uri: RETURN, scope: 'openid email profile offline_access', state, nonce, code_challenge: b64u(new Uint8Array(digest)), // PKCE, S256 only code_challenge_method: 'S256', }); // Keep verifier, state and nonce for the callback: a short-lived, // HTTP-only, Secure cookie (or your own session store). const saved = encodeURIComponent(JSON.stringify({ verifier, state, nonce })); return new Response(null, { status: 302, headers: { Location: url.toString(), 'Set-Cookie': `uffda_signin=${saved}; Path=/auth/uffda; Max-Age=600; HttpOnly; Secure; SameSite=Lax`, }, }); }They sign in at the hub
If they aren't signed in yet, they sign in with Google. The hub checks that your app is shared with them; if it isn't, the hub tells them so on its own page. For apps a hub admin doesn't own, it asks them once whether to share their name and email with you, and a no comes back as
error=access_denied. Otherwise it sends them back withcode,stateandiss.Swap the code and check the ID token
Within 60 seconds, and only once. The ID token lives 5 minutes: check that it's ES256 from the hub's keys, header
typisJWT,issishttps://uffdahub.com,audis your client id, it hasn't expired, andnoncematches.src/signin.jsjs // GET /auth/uffda/callback?code=...&state=...&iss=https://uffdahub.com import { createRemoteJWKSet, jwtVerify } from 'jose'; const JWKS = createRemoteJWKSet(new URL('https://uffdahub.com/.well-known/jwks.json')); export async function finishSignIn(request, env, saved) { const q = new URL(request.url).searchParams; if (q.get('error')) return showError(q.get('error')); // access_denied, login_required... if (q.get('state') !== saved.state) return showError('state'); if (q.get('iss') !== 'https://uffdahub.com') return showError('iss'); // Swap the code within 60 seconds. It works once. const res = await fetch('https://uffdahub.com/oidc/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', Authorization: 'Basic ' + btoa(`${env.UFFDA_CLIENT_ID}:${env.UFFDA_CLIENT_SECRET}`), }, body: new URLSearchParams({ grant_type: 'authorization_code', code: q.get('code'), redirect_uri: RETURN, code_verifier: saved.verifier, }), }); if (!res.ok) return showError('token'); const tokens = await res.json(); // id_token, access_token, refresh_token const { payload } = await jwtVerify(tokens.id_token, JWKS, { issuer: 'https://uffdahub.com', audience: env.UFFDA_CLIENT_ID, algorithms: ['ES256'], typ: 'JWT', }); if (payload.nonce !== saved.nonce) return showError('nonce'); const user = await findOrLinkUser(env, payload); // see "Linking accounts" return startYourSession(user, tokens.refresh_token); }The same swap with curlsh curl https://uffdahub.com/oidc/token \ -u "$UFFDA_CLIENT_ID:$UFFDA_CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code="$CODE" \ -d redirect_uri=https://yourapp.example/auth/uffda/callback \ -d code_verifier="$VERIFIER"What comes backjson { "token_type": "Bearer", "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ii4uLiJ9...", "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCJ9...", "expires_in": 600, "refresh_token": "...", "scope": "openid email profile offline_access" }Inside the ID tokenjson { "iss": "https://uffdahub.com", "aud": "your-client-id", "sub": "k3v9q2...", // private to your app, never changes "iat": 1795000000, "exp": 1795000300, // 5 minutes "azp": "your-client-id", "nonce": "the nonce you sent", "email": "sam@example.com", // with the email scope "email_verified": true, "name": "Sam Rivera", // with the profile scope "picture": "https://lh3.googleusercontent.com/..." }Check in once a day
Refresh tokens last 60 days and rotate: each one works once and a new one comes back.
invalid_grantmeans the person can't use your app any more, or signed out of the hub, so end their session. even checks once a day.src/session.jsjs // Once a day: is this person still allowed in? const res = await fetch('https://uffdahub.com/oidc/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded', Authorization: 'Basic ' + btoa(`${env.UFFDA_CLIENT_ID}:${env.UFFDA_CLIENT_SECRET}`), }, body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: session.refresh }), }); if (res.status === 400 && (await res.json()).error === 'invalid_grant') { return endSession(session); // lost access, or signed out of the hub } session.refresh = (await res.json()).refresh_token; // each one works once
Linking accounts
If your app already has accounts, the first sign-in through the hub needs to find the right one. Look the person up by sub first. If there's no match, match by email, but only when email_verified is true, and save the sub on that account. From then on, sub is what counts, so a later email change at Google doesn't move anyone's data. Refuse an account that's already linked to a different sub.
// The first time someone arrives through the hub, find their account by sub,
// then by a verified email, and save the sub on it. After that, sub is what counts.
async function findOrLinkUser(env, claims) {
const bySub = await db.userBySub(claims.sub);
if (bySub) return bySub;
if (!claims.email || claims.email_verified !== true) throw new Error('No verified email');
const byEmail = await db.userByEmail(claims.email.toLowerCase());
if (byEmail?.uffda_sub && byEmail.uffda_sub !== claims.sub) {
throw new Error('That account is already linked to another uffda account');
}
if (byEmail) return db.setSub(byEmail.id, claims.sub);
return db.createUser({ sub: claims.sub, email: claims.email, name: claims.name });
}Signing out
- Your Sign out button: end your own session, then send the browser to
/oidc/logoutwith yourclient_idand apost_logout_redirect_urion the same site as one of your return addresses. The hub asks whether to sign out of the hub too, then sends them back. - Signed out at the hub: the hub signs them out of every app. It posts a
logout_tokento your sign-out address, and their refresh tokens stop working. Check the token like an ID token, except the headertypislogout+jwt, it has the back-channel logout event and nononce. End every session for thatsuband answer 200.
// POST /auth/uffda/logout: the hub says someone signed out of the hub.
export async function backChannelLogout(request, env) {
const form = await request.formData();
try {
const { payload } = await jwtVerify(String(form.get('logout_token')), JWKS, {
issuer: 'https://uffdahub.com',
audience: env.UFFDA_CLIENT_ID,
algorithms: ['ES256'],
typ: 'logout+jwt',
});
const event = 'http://schemas.openid.net/event/backchannel-logout';
if (!payload.sub || 'nonce' in payload || !payload.events?.[event]) throw new Error();
await endEverySessionFor(payload.sub);
return new Response(null, { status: 200 });
} catch {
return new Response('Bad logout token', { status: 400 });
}
}
// Your own Sign out button: end your session, then let the hub ask about the hub.
const out = new URL('https://uffdahub.com/oidc/logout');
out.searchParams.set('client_id', env.UFFDA_CLIENT_ID);
out.searchParams.set('post_logout_redirect_uri', 'https://yourapp.example/login?out=1');Claude and MCP.
The hub runs one MCP server, the gateway at https://uffdahub.com/mcp. People connect Claude to it once. From then on Claude sees the tools of every app they can use, and the hub forwards each call to the right app as the right person.
How the gateway works
Claude connects once
With OAuth, at the hub. The person sees which of their apps Claude will be able to use, and chooses Allow.
Each person gets their own tool list
tools/listshows only tools from apps this person can see right now and hasn't switched off on their account page. Each tool is named after its app (even'ssplit_balancesbecomeseven_split_balances) and keeps the description an admin approved, not whatever the app says today.Every call is checked again
On
tools/callthe hub looks the tool up in this person's list again, so access taken away an hour ago is gone now. Who is calling comes only from the signed-in connection, never from the tool's arguments.Your app gets a hub pass
The hub calls your MCP address with a hub pass: a token it signs that names your app and this person's private id for it, and lasts 60 seconds. Your app does the work as that person and answers.
The call is logged
Which app, which tool, when, and whether it worked. Kept 90 days. What was asked and answered is never logged.
Tools marked readOnlyHint: true show as Reads on the hub. Everything else shows as Makes changes, and the gateway tells Claude to ask the person before using a tool that changes data. Mark your tools honestly: the hub passes readOnlyHint, destructiveHint, idempotentHint and openWorldHint through to Claude.
Your MCP endpoint
Run an MCP server over Streamable HTTP at an https address, like https://yourapp.example/mcp. The hub sends one JSON-RPC message per POST, with MCP-Protocol-Version: 2025-06-18 and Accept: application/json, text/event-stream. Answer with plain JSON or an SSE stream. It needs tools/list and tools/call.
Accept the hub pass in Authorization: Bearer. Check it like an ID token, with the header typ set to hub-pass+jwt and no nonce. Also check that scope is mcp, that it lives 60 seconds at most (exp - iat), and that you haven't seen its jti before. Act only as the person in sub. The pass also has app (your app's page name on the hub) and, if they've been shared with you, email and name.
// POST /mcp on your app. Every call from the hub carries a hub pass.
const seen = new Map(); // jti -> expiry. Use KV or a table if you run more than one instance.
export async function mcp(request, env) {
const auth = request.headers.get('Authorization') || '';
let pass;
try {
({ payload: pass } = await jwtVerify(auth.replace(/^Bearer /, ''), JWKS, {
issuer: 'https://uffdahub.com',
audience: env.UFFDA_CLIENT_ID,
algorithms: ['ES256'],
typ: 'hub-pass+jwt',
}));
} catch {
return new Response('Unauthorized', { status: 401 });
}
if (pass.scope !== 'mcp' || pass.exp - pass.iat > 60 || 'nonce' in pass) {
return new Response('Unauthorized', { status: 401 });
}
if (seen.has(pass.jti)) return new Response('Already used', { status: 401 });
seen.set(pass.jti, pass.exp);
const user = await db.userBySub(pass.sub); // act as this person, and only them
const msg = await request.json(); // one JSON-RPC message
return Response.json(await handle(msg, user)); // plain JSON is fine; SSE works too
}| Limit | |
|---|---|
| Tools per app | 50 |
| Tool names | Letters, digits, _ and -, up to 48 characters |
| Descriptions | Up to 2,000 characters; titles up to 80 |
| Answer size | 256 KB per call |
| Time to answer | 25 seconds |
Loading your tools
Once sign-in is on, an admin puts your MCP address on your app's edit page, under Claude, and chooses Save and load tools. The hub calls tools/list once and pins what it gets: names, titles, descriptions, input schemas and hints. Claude only ever sees the pinned version, so a change in your app reaches Claude only when an admin loads the tools again. Ask for that when you add or change a tool.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "list_balances",
"title": "Check balances",
"description": "What you and each friend owe each other, in dollars.",
"inputSchema": { "type": "object", "properties": {} },
"annotations": { "readOnlyHint": true }
},
{
"name": "add_expense",
"title": "Add an expense",
"description": "Adds a shared cost and splits it.",
"inputSchema": {
"type": "object",
"properties": { "text": { "type": "string" } },
"required": ["text"]
},
"annotations": { "readOnlyHint": false, "destructiveHint": false }
}
]
}
}Adding uffda to Claude
This is the part for the people using your app, so it's worth a line in your own help pages.
Add a custom connector
In Claude's connector settings, add a custom connector with the address
https://uffdahub.com/mcp.Sign in and allow
Claude opens the hub. Sign in, check the list of apps, and choose Allow.
Choose apps
Any app can be switched off for Claude on the hub's account page, under Claude. New apps that are shared with you show up by themselves.
Security and data.
What your app receives
A private sub for each person, different in every app, so apps can't match people across the hub. Email, name and picture only with those scopes, and only after the person agrees, unless a hub admin owns the app.
Short-lived tokens
Codes last 60 seconds and work once. ID tokens last 5 minutes, access tokens 10 minutes and hub passes 60 seconds. Refresh tokens last 60 days and rotate on every use.
Secrets
Client secrets and session tokens are stored only as hashes. Tokens are signed with ES256 and the hub's public keys are at /.well-known/jwks.json.
The call log
For each Claude call: who, which app, which tool, when, and whether it worked. Kept 90 days. Never the question or the answer.
Who can get in
The hub is invite-only, unless an admin turns on open sign-up for an app. People sign in to your app only if it's shared with them on the hub, or you own it.
Results are data
The gateway tells Claude to treat what your tools return as information from your app, never as instructions, and not to use one app's results to drive another app.
The full details are in our privacy policy and terms of service. If your app collects something new about people, say so in your own privacy notice.
Questions.
Can anyone add an app?
Anyone on the hub can list an app and choose who sees it. Turning on Sign in with uffda and Claude is done by a hub admin, so email dev@runflip.com when you're ready.
Do I need a library?
No. Any OpenID Connect client works, and so does plain fetch plus WebCrypto: even does it in about 230 lines with no dependencies. A library like jose saves you writing the token checks.
Can I try it on my own computer?
Yes. A return address can be http://localhost, so add your local callback next to the real one.
What happens if my app isn't shared with someone?
The hub stops them on its own page and tells them to ask the app's owner to share it. With prompt=none they come back to your callback with error=access_denied instead.
Can people sign in without Google?
Not yet. The hub uses Google for now, and sign-in by email code may come later.
Does my app still need its own sign-out?
Yes. Your app keeps its own sessions. The hub tells you when someone signs out of the hub, and your refresh check catches anyone who lost access.
Why didn't Claude pick up my new tool?
The hub pins your tools when an admin loads them. Ask for Save and load tools again after you change them.
Does the hub see my app's data?
Tool calls pass through the hub on their way to Claude, but the hub doesn't keep them. It logs only which app and tool, when, and whether it worked.
Can I change the button's colours?
Please don't. Pick the navy, white, cream or outline style that fits your page. If none of them works, email us.
Ready to plug in.
Email dev@runflip.com with your app's name and return address, and we'll turn on sign-in.