My Custom MCP Server Keeps Losing Authentication After a Few Minutes — How Do I Fix It?

Last updated: May 14, 2026

This happens when your OAuth server doesn't issue a long-lived refresh token — usually because offline_access isn't enabled or the refresh token TTL is too short. Enable offline_access in your OAuth server's scope configuration and set the refresh token TTL to at least several hours (ideally days or months) so Gumloop can keep the session alive between tool calls.

Symptoms

  • The first tool call after connecting your custom MCP server succeeds, but subsequent calls fail a few minutes later.

  • Your MCP server logs show the agent's requests arriving with auth_email: null or auth_sub: null — as if Gumloop sent the request without credentials.

  • You see 401 Unauthorized responses on your server side after the initial successful call.

  • Removing and re-adding the MCP server temporarily fixes it, but the issue comes back after a few minutes.

Cause

When you add a custom MCP server that uses OAuth (including Dynamic Client Registration), Gumloop registers with grant_types: ["authorization_code", "refresh_token"]. This tells your authorization server that Gumloop wants to use refresh tokens to keep the session alive.

However, Gumloop does not explicitly request the offline_access scope — it only requests scopes your server advertises in its OAuth metadata (scopes_supported). Many OAuth servers require offline_access to be granted before they will include a refresh token in the token response.

Here's what happens when this is misconfigured:

  1. Gumloop gets an access token during the initial OAuth flow — the first call works.

  2. The access token expires (often in 5–15 minutes).

  3. Gumloop looks for a stored refresh token to mint a new access token, but either no refresh token was issued or it has already expired.

  4. Without a valid refresh token, the next tool call is sent with an expired access token — your server rejects it as unauthorized.

Even if your server does issue a refresh token, a very short TTL (e.g., 30 minutes) causes the same problem. Gumloop only refreshes the token right before a tool call. If no tool call happens within the refresh token's lifetime, it expires and the session breaks.

How to Fix It

Step 1: Enable offline_access on your OAuth server

In your OAuth authorization server configuration:

  1. Add offline_access to the list of supported scopes (scopes_supported in your OAuth metadata / .well-known/oauth-authorization-server).

  2. Ensure that clients registered via DCR are granted offline_access by default, or that it is included in the scopes granted during the authorization flow.

  3. Verify your token endpoint returns a refresh_token field in the JSON response after the initial code exchange.

Step 2: Set a long-lived refresh token TTL

Configure your refresh token TTL to survive periods of inactivity. Recommended values:

  • Access token TTL: 15 minutes to 1 hour (short is fine — Gumloop refreshes before each call).

  • Refresh token TTL: At least 7 days, ideally 30–180 days. Most major providers (Google, Microsoft, Okta) use refresh tokens valid for months.

A 30-minute refresh token will break the session if the agent is idle for more than 30 minutes between tool calls — this is the most common cause of this issue.

Step 3: Reconnect the MCP server in Gumloop

After updating your OAuth server configuration, you need to reconnect so Gumloop gets a new token with the updated scopes and TTL:

  1. Go to Settings → Credentials (MCP Servers).

  2. Find your custom MCP server credential and remove it.

  3. Re-add the MCP server and complete the OAuth flow again.

  4. Test by asking your agent to list the server's available tools, waiting 10+ minutes, and then asking it to use a tool again.

How to Verify It Worked

  • After reconnecting, check your OAuth server's /token response — it should now include a refresh_token field alongside the access_token.

  • Use your agent, wait longer than the access token TTL (e.g., 10–15 minutes), then use it again. The second call should succeed without re-authentication.

  • Check your server logs — you should see Gumloop making a POST to your /token endpoint with grant_type=refresh_token before the second tool call.

Still Need Help?

If this didn't resolve your issue, reach out to support at support@gumloop.com.

Related Docs