Add OAuth 2.0 authentication support to the SerpApi MCP server

[sonika-serpapi]

While working on the application to submit this MCP server to Anthropic's official connector library, I noticed they require OAuth 2.0 for authenticated services. This is needed to be featured as an official connector here:

Users can still use our MCP as a custom connector by adding it themselves (ref).

Current authentication methods we support:

• Path-based Authentication (recommended)
  /YOUR_API_KEY/mcp

• Header-based Authentication
  Authorization: Bearer YOUR_API_KEY

These methods work well for direct integrations but Anthropic's connector directory expects OAuth 2.0 authentication. Without OAuth support, we are unable to list the MCP as an official connector and offer a seamless "Connect SerpApi" experience in Claude.

Not sure if this is possible now, or something we want to work on, but I am noting it here as a finding.

Reference: https://claude.com/docs/connectors/building/submission#submission-requirements

[louzt]

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.

[louzt]

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.

[sonika-serpapi]

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?

[adarshdigievo]

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

[ilyazub]

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

[louzt]

@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.

[sonika-serpapi]

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