Setting Up OAuth for Your MCP Server

Shredly supports OAuth 2.0 for MCP servers, allowing AI agents (like Claude) to authenticate on behalf of users before making tool calls. This guide walks through how the OAuth flow works and how to configure it for your provider.

How It Works

When an AI agent connects to your MCP server and no token is present, Shredly acts as an OAuth proxy — handling the full authorization code flow on your behalf and returning an access token to the agent.

The high-level flow:

1. Agent hits your MCP endpoint → receives a 401 with OAuth discovery hints
2. Agent discovers the authorization server metadata (endpoints, scopes)
3. Agent registers as a client (dynamic registration)
4. Agent redirects the user to your provider's login page
5. User authenticates → your provider redirects back to Shredly's callback
6. Shredly exchanges the authorization code for a token via your token_url
7. Agent receives the access token and uses it for subsequent MCP calls

---

Configuration Fields

When creating or updating an MCP server, provide an oauth object with the following fields:

Field	Required	Description
authorization_url	Yes	Your provider's authorization endpoint — where users are sent to log in
token_url	Yes	The endpoint that exchanges the authorization code for an access token
client_id	Yes	OAuth client ID from your provider
client_secret	Yes	OAuth client secret — stored securely, never exposed to end users
scopes	No	Array of scopes to request (e.g. ["openid", "profile", "email"])
extra_params	No	Additional query parameters appended to the authorization URL

---

Redirect URI

Regardless of provider, you must register the following redirect URI with your OAuth app:

https://mcp.shredly.io/mcp/{your-slug}/callback

Replace {your-slug} with the slug of your MCP server (e.g. https://mcp.shredly.io/mcp/my-app/callback).

---

Provider Examples

Google OAuth

OAuth app setup:

1. Go to Google Cloud Console → APIs & Services → Credentials
2. Create an OAuth 2.0 Client ID (Web application)
3. Add your redirect URI: https://mcp.shredly.io/mcp/{slug}/callback

Configuration:

{
  "oauth": {
    "authorization_url": "https://accounts.google.com/o/oauth2/v2/auth",
    "token_url": "https://your-backend.com/auth/google",
    "client_id": "your-client-id.apps.googleusercontent.com",
    "client_secret": "your-client-secret",
    "scopes": ["openid", "profile", "email"],
    "extra_params": {
      "access_type": "offline"
    }
  }
}

access_type: offline is recommended if you need a refresh token.

note

Google OAuth requires a custom token_url in your own backend. You cannot point directly to Google's token endpoint because the token returned by Google is not a token your backend can validate on MCP tool calls. Your token_url should exchange the code with Google, use the resulting Google access token to authenticate or create a session in your system, and return an access_token that is valid in your backend. See Custom Token Endpoints for the required request/response format.

---

Auth0

OAuth app setup:

1. In your Auth0 dashboard, create a Regular Web Application
2. Add your redirect URI under Allowed Callback URLs: https://mcp.shredly.io/mcp/{slug}/callback

Configuration:

{
  "oauth": {
    "authorization_url": "https://your-tenant.auth0.com/authorize",
    "token_url": "https://your-tenant.auth0.com/oauth/token",
    "client_id": "your-auth0-client-id",
    "client_secret": "your-auth0-client-secret",
    "scopes": ["openid", "profile", "email"]
  }
}

With Auth0, the token_url points directly to Auth0's token endpoint — no custom proxy needed. Auth0 speaks standard OAuth 2.0 and returns { access_token, token_type, expires_in } natively.

---

Custom Token Endpoints

If you need custom logic during token exchange (e.g. bridging to an internal session system like Shredly does for Google), you can provide your own token_url.

Your custom endpoint must:

Accept a POST request with Content-Type: application/x-www-form-urlencoded containing:

Field	Description
grant_type	Always authorization_code
code	The authorization code from the provider
redirect_uri	The Shredly callback URL (https://mcp.shredly.io/mcp/{slug}/callback)
client_id	The client ID from your OAuth config
client_secret	The client secret from your OAuth config
code_verifier	PKCE verifier (if PKCE was used in the authorization request)

Return a JSON response:

{
  "access_token": "the-token-the-agent-will-use",
  "token_type": "bearer",
  "expires_in": 3600
}

The access_token returned here is what the AI agent will send as the Authorization: Bearer (or custom ApiKey) header on all subsequent MCP tool calls.

---

Troubleshooting

redirect_uri_mismatch from your provider The redirect URI registered in your OAuth app doesn't match. Make sure you've added exactly https://mcp.shredly.io/mcp/{your-slug}/callback to your provider's allowed redirect URIs.

Agent stops after the login page / token not returned Confirm your token_url endpoint returns the required JSON format with access_token, token_type, and expires_in.

OAuth flow doesn't start (agent gets a plain 401) The oauth config is missing or not saved on your MCP server. Verify it's set by fetching your server config.