Add OAuth 2.0 authentication support to the SerpApi MCP server #38

Activity

1. louzt commented on Jun 10, 2026

   

   louzt

   on Jun 10, 2026

   Contributor

   More actions

   Confirmed: this is possible and well-supported in the current ecosystem. The MCP 2025-11-25 spec standardized OAuth 2.0 as a transport-level auth mechanism, and fastmcp>=3.2.0 (already a dep in pyproject.toml) ships a complete OAuth infrastructure out of the box.

   The minimum viable integration is ~4 lines of config:

   from fastmcp.server.auth.providers.google import GoogleProvider
   
   auth = GoogleProvider(
       client_id=os.environ["GOOGLE_OAUTH_CLIENT_ID"],
       client_secret=os.environ["GOOGLE_OAUTH_CLIENT_SECRET"],
   )
   mcp = FastMCP("SerpApi MCP Server", auth=auth)

   fastmcp.server.auth.providers ships 16+ built-in integrations (Google, GitHub, Auth0, AWS Cognito, Azure AD, Clerk, WorkOS, Keycloak, Supabase, etc.) plus a generic OAuthProxy for any OIDC-compliant IdP and JWTVerifier for direct JWT validation. The proxy handles authorization-code flow, PKCE, token refresh, and JWKS-based signature verification — exactly what the Anthropic connector submission requirements expect to see.

   A practical PR scope for this server would be:

   1. Pick an IdP strategy (Google Workspace for org-level access, GitHub for dev-facing, custom OIDC, etc.).
   2. Layer the OAuth provider as a Starlette middleware alongside (not replacing) the existing ApiKeyMiddleware, so direct API-key path/header auth keeps working for self-hosted users.
   3. Define scopes (e.g. search:read, search:execute).
   4. Map the OAuth sub claim to a SerpApi API key (one-time provisioning flow) so the existing SerpApi HTTP calls in search() keep working unchanged.
   5. Update README + the hosted mcp.serpapi.com deploy to expose OAuth discovery endpoints (/.well-known/oauth-authorization-server, /oauth/token, etc.).

   Items 1 and 4 are the real decision points — the rest is mechanical wiring. Happy to scope a PR for any of (a) full implementation, (b) just the discovery endpoints + a fixture-based test harness, or (c) a design doc with a concrete user-flow diagram, depending on what the maintainer wants to pursue.

   A few related items that are in flight on the transport/auth boundary and may be worth cross-linking when this lands:

   • [MCP] Add resource annotations to engines_index #47 [MCP] Add resource annotations to engines_index — touches the same middleware region; can be tested under the new auth layer.
   • [MCP] Migrate static engine resources to ResourceTemplate #48 [MCP] Migrate static engine resources to ResourceTemplate — the ResourceTemplate auth parameter (AuthCheck | list[AuthCheck]) ties directly into OAuth scope checks once available.

   👍React with 👍2Reacted by Sonika Arora and vm-serpapi
2. louzt commented on Jun 10, 2026

   

   louzt

   on Jun 10, 2026

   Contributor

   More actions

   Quick follow-up: I've drafted a design doc as #49 (docs: add OAuth 2.0 design proposal tracking #38) so the work has a concrete starting point if the team wants to pursue this. The doc lays out a 5-phase plan sliced into reviewable PRs, with the smallest unblocker being a ~50-line discovery endpoint skeleton (/.well-known/oauth-authorization-server) that the Anthropic connector directory can scrape to verify OAuth support, without yet wiring any actual auth.

   The doc also has a decision matrix and 5 open questions for the maintainer (IdP choice, provisioning strategy, token lifetime, hosted-only vs. self-hosted, backward-compat window). Happy to drive Phase 1 (the discovery skeleton) as a follow-up PR once the IdP direction is set, or split the work differently if the team prefers. Tagging @sonika-serpapi since this connects to the original connector submission work.

   👍React with 👍1Reacted by Sonika Arora
3. louzt

   added a commit that references this issue on Jun 10, 2026

   docs: add OAuth 2.0 design proposal tracking serpapi#38

   ...

   f97becb
4. sonika-serpapi commented on Jun 16, 2026

   

   sonika-serpapi

   on Jun 16, 2026

   Author

   More actions

   Thank you for sharing your work @louzt! @vm-serpapi @adarshdigievo would you be open to taking a look at the approach here and sharing your thoughts?
5. adarshdigievo commented on Jun 17, 2026

   

   adarshdigievo

   on Jun 17, 2026

   Member

   More actions

   I took a look at the proposal from @louzt

   Third party OAuth and SERPAPI_DEFAULT_API_KEY does not work in our use-case. This is because the search credits are tied to users in our case. Each call to SerpApi MCP's search tool costs 1 API credits from the users account. We cannot force users to sign-in via Google/GitHub or other providers since they may not have an account on these platforms or they may not be willing to link it with their SerpApi account.

   Since we need to map requests to a specific user based on their SerpApi account, we need to build a custom OAuth server.

   @sonika-serpapi I think we can open an issue on our public roadmap since this change would require changes to our core backend. The relative amount of work needed in this repo, the MCP server, is small compared to the actual changes required in our core backend. Also, as @vm-serpapi noted, this is a security-sensitive change since it involves building, auditing, and maintaining a new form of auth.

   Related issue on our public roadmap: serpapi/public-roadmap#1412

   👍React with 👍1Reacted by vm-serpapi
6. ilyazub commented on Jun 17, 2026

   

   ilyazub

   on Jun 17, 2026

   Collaborator

   More actions

   Let's do this and other pre-requisites to publish SerpApi MCP to the official Claude Connectors.

   👍React with 👍1Reacted by Sonika Arora
7. louzt commented on Jun 17, 2026

   

   louzt

   on Jun 17, 2026

   Contributor

   More actions

   @adarshdigievo That is an absolutely correct assessment. You hit the exact friction point: transport-level identity delegation completely breaks a strict per-account credit billing model unless you introduce heavy user-mapping friction.

   My goal with this doc was to map out what leveraging the existing fastmcp Auth providers would look like. However, if building a first-party custom OAuth server in the core SerpApi backend is now on the roadmap that is 100% the superior, enterprise-grade path. It keeps billing natively tied to the SerpApi identity and perfectly fulfills Anthropic's connector requirements.

   I had some ideas about it but since the heavy lifting now moves out of this open-source MCP repo and into your proprietary core infrastructure, I will close this design PR to keep your tracker clean.

   Glad this helped unblock the architectural conversation around the Claude Connector submission. As an external contributor, my operational scope ends at this public boundary. Best of luck to your internal backend team with the custom OAuth implementation if you decide to start that path and best of successes on the near future and long run as a proyect.
8. sonika-serpapi commented on Jun 17, 2026

   

   sonika-serpapi

   on Jun 17, 2026

   Last edited by sonika-serpapi

   Author

   More actions

   Thank you @louzt @ilyazub @adarshdigievo for looking into it!

   Really appreciate you contributing to unblocking this work.

   I noticed a couple other platforms also require OAuth like OpenAI's official app library and smithery.ai (an MCP marketplace) where it would be good to be present.

   I've mentioned it also on this issue: serpapi/public-roadmap#1412

   👍React with 👍4Reacted by Adarsh Divakaran, vm-serpapi, ilyazub and David Mireles
9. AutumroseS commented on Sep 10, 2026

   

   AutumroseS

   on Sep 10, 2026

   More actions

   Request here:
   Intercom

   👀React with 👀1Reacted by David Mireles