How Ref.tools made its product agentic & enterprise-ready without rebuilding auth

Ref is a documentation search MCP server for coding agents. It lets AI tools like Claude, Cursor, VS Code, and ChatGPT search both public and private documentation directly, finding the exact snippet they need without blowing up the context window.

The product serves developers and engineering teams who want their AI coding tools to work correctly with the libraries they actually use. There is no separate IDE plugin and no copy-paste workflow. Developers point their AI tool at Ref's MCP endpoint, and the agent handles the rest.

That architecture made auth both critical and complicated. Every developer connecting to Ref's server through their IDE needed to be authenticated correctly. And as Ref began onboarding enterprise customers, teams with their own identity providers and SSO policies, the gap between pilot-grade and production-grade auth became impossible to ignore.

MCP as a core delivery mechanism

MCP is the protocol layer that lets AI tools like Claude, Cursor, and VS Code connect directly to external products in real time. For Ref, it is not just an integration, it is the entire delivery channel. Instead of asking developers to export documentation and paste it into a prompt, Ref's MCP server lets the coding agent go find what it needs mid-task, pulling back exactly the documentation snippet it was looking for.

What makes auth hard in this context is the layered flow a single connection involves:

• A developer configures Ref's MCP server in their IDE, such as Cursor or VS Code
• The AI tool connects to Ref on the developer's behalf through a browser-based OAuth consent flow
• If the developer belongs to an enterprise team with SSO, that login needs to route through their company's identity provider, such as Okta, before access is granted

Each step in that chain must be secure, scoped, and spec-compliant. The full flow from IDE to Scalekit to Firebase to identity provider is non-trivial to build correctly, and for a product like Ref it has to work reliably for every developer on every team.

The Challenge: Production-grade auth on top of Firebase

• Pilot-grade security was a blocker. The existing setup used header-based authentication, acceptable for early users and known parties, but not something a procurement team or security review would accept.
• Enterprise customers expected SSO. Larger engineering teams wanted to log in through Okta or their existing identity provider, not create new credentials for another tool.
• Firebase was more than an auth layer. It was the primary database, storing per-user search history, indexed resources, and team access data tied directly to Firebase user IDs. Any solution had to authenticate users through a new layer while keeping Firebase intact as the underlying data store.
• Building from scratch was not viable. Supporting OAuth 2.1, wiring up SSO per identity provider, and maintaining all of it while shipping core product was not a realistic path for a small team.

"The pilot worked. The hard part was making it enterprise-ready without rebuilding the auth stack we'd already built on top of Firebase."

Matt Dailey

Founder, Ref

How Scalekit shipped in a day

Ref integrated Scalekit in two modular pieces, MCP auth and SSO, without replacing Firebase or migrating any existing user data. Firebase stayed exactly as it was. Scalekit handled everything that sits in front of it. Highlights: 

• Bring Your Own Auth for MCP - When a developer connects through Cursor, VS Code, or Claude Desktop, the request flows to Scalekit, which redirects to Ref's existing Firebase login. Firebase handles the session; Scalekit receives confirmation of the authenticated user and issues a scoped token back to the MCP host. Firebase stays the source of truth for all user data. Scalekit owns the OAuth layer.
• OAuth 2.1 + PKCE - Spec-compliant authorization code flow with a full consent screen surfacing tool-level permissions before any data is accessed
• SSO for enterprise customers - When an enterprise team wants their developers to log in using their existing Okta setup, Scalekit orchestrates the SAML or OIDC handshake between Ref and the customer's identity provider. Ref associates the customer's domain in the Scalekit dashboard; every user from that domain is routed to SSO automatically
• Self-serve SSO configuration - Enterprise customers configure their own SSO connection via a Scalekit-generated admin portal link, with no involvement from Ref's engineering team and no DNS changes required
• Token validation - Scalekit issues JWTs; Ref's MCP server validates them on every inbound call. Credentials never touch the MCP server itself

The full auth flow looks like this: Claude or Cursor connects, Scalekit handles OAuth, Firebase completes authentication, and if the developer's domain is mapped to an SSO connection, Scalekit routes to Okta. A scoped token comes back to the MCP host. Firebase continues to serve all per-user data throughout.

With Scalekit handling both MCP auth and SSO, Ref is now open to enterprise customers and the broader MCP ecosystem without the auth gaps that would stop a security review. The integration required no changes to the Firebase data model and no migration of existing users.

"It took about a day to get an MVP of SSO + MCP OAuth for Ref, which uses Firebase auth under the hood. The Scalekit docs were clear and the OAuth debugger made it easy to step through the process and figure out exactly where things were going wrong. It felt like both products were purpose-built for me."

Matt Dailey

Founder, Ref