OAuth Refresh Tokens for MCP: Complete Guide
One of the biggest advantages of OAuth is that users don't need to sign in every time an application accesses a protected resource.
This is possible because OAuth separates short-lived Access Tokens from longer-lived Refresh Tokens.
When an Access Token expires, the client can request a new one using its Refresh Token, allowing users to continue working without repeating the entire authentication process.
For Model Context Protocol (MCP) clients like Cursor and Claude Code, Refresh Tokens help maintain secure, long-running connections to remote MCP servers while reducing unnecessary login prompts.
In this guide, you'll learn how Refresh Tokens work, when they're issued, how token rotation improves security, and the best practices for OAuth-enabled MCP deployments.
Quick Answer
A Refresh Token is an OAuth credential used to obtain a new Access Token after the current one expires. Refresh Tokens are issued by the Authorization Server, never sent to the MCP server, and may not be available in every OAuth deployment.
What Is a Refresh Token?
A Refresh Token is a credential issued during the OAuth authorization process.
Unlike an Access Token, it is not used to access protected resources directly.
Instead, it allows the OAuth client to request a new Access Token without requiring the user to authenticate again.
A simplified flow looks like this:
User
│
OAuth Login
│
▼
Authorization Server
│
├── Access Token
└── Refresh Token
The client stores both tokens securely.
The Access Token is used for API requests.
The Refresh Token remains unused until the Access Token expires.
Why Access Tokens Expire
Access Tokens are intentionally short-lived.
If an attacker obtains one, its usefulness is limited because the token eventually becomes invalid.
A typical lifecycle looks like this:
Access Token Issued
│
▼
Requests to MCP Server
│
▼
Token Expires
│
▼
Refresh Required
Using short-lived Access Tokens is a widely recommended OAuth security practice.
Instead of extending Access Token lifetimes indefinitely, OAuth relies on Refresh Tokens to maintain long-running sessions.
Why MCP Uses Refresh Tokens
Remote MCP servers often provide access to services that users interact with for extended periods.
Examples include:
- source code repositories
- cloud platforms
- documentation systems
- project management tools
- enterprise APIs
- internal business applications
Without Refresh Tokens, users would need to repeat the OAuth login process every time an Access Token expired.
Refresh Tokens provide a smoother user experience while preserving the security benefits of short-lived Access Tokens.
Access Token vs Refresh Token
Although they work together, these two token types have very different responsibilities.
| Access Token | Refresh Token |
|---|---|
| Used for API requests | Used to obtain new Access Tokens |
| Usually short-lived | Usually longer-lived |
| Sent to the MCP server | Sent only to the Authorization Server |
| Included in Authorization headers | Never included in API requests |
| Represents current authorization | Maintains long-term authorization |
How Refresh Tokens Work
The Refresh Token remains inactive until the current Access Token expires.
When that happens, the client contacts the Authorization Server—not the MCP server—to obtain a new Access Token.
A simplified refresh flow looks like this:
User
│
▼
OAuth Login
│
▼
Authorization Server
│
├── Access Token
└── Refresh Token
│
▼
OAuth Client
│
Access Token Expires
│
▼
Use Refresh Token
│
▼
Authorization Server
│
├── New Access Token
└── (Optional) New Refresh Token
If the Refresh Token is still valid, the Authorization Server issues a new Access Token.
The user continues working without needing to sign in again.
Refresh Tokens Never Reach the MCP Server
One of the most important concepts in OAuth is that the MCP server never receives the Refresh Token.
Instead, responsibilities are split between two systems:
- Authorization Server manages authentication, token issuance, and token refresh.
- MCP Server validates Access Tokens and serves protected tools and resources.
A simplified architecture looks like this:
Refresh Token
Client ----------------------------► Authorization Server
│
▼
New Access Token
│
▼
Client ----------------------------► MCP Server
Authorization:
Bearer Access Token
This separation reduces risk because the MCP server only processes temporary Access Tokens.
Refresh Token Rotation
Modern OAuth deployments often implement Refresh Token rotation.
Instead of allowing the same Refresh Token to be reused indefinitely, the Authorization Server issues a new Refresh Token every time one is redeemed.
Refresh Token A
│
▼
Authorization Server
│
├── Access Token
└── Refresh Token B
Once the new token is issued, the previous Refresh Token is typically invalidated.
This significantly reduces the impact of a stolen Refresh Token because replay attacks become much more difficult.
Many modern Authorization Servers recommend or require token rotation, especially for public clients.
The offline_access Scope
Some Authorization Servers require clients to request the offline_access scope before issuing Refresh Tokens.
The purpose of this scope is to indicate that the client may continue accessing protected resources even when the user is no longer actively interacting with the application.
Typical examples include:
- desktop applications
- IDE integrations
- long-running background processes
- scheduled automation
- enterprise workflows
Not every Authorization Server supports offline_access, and requesting it does not guarantee that a Refresh Token will be issued.
The final decision always belongs to the Authorization Server.
When Refresh Tokens Are Not Issued
OAuth does not require every Authorization Server to issue Refresh Tokens.
Some deployments intentionally avoid them.
Examples include:
- short-lived development sessions
- highly sensitive environments
- one-time authentication flows
- systems with strict security requirements
In these situations, users simply authenticate again after the Access Token expires.
Applications should never assume that a Refresh Token will always be available.
Common Refresh Token Errors
Refresh-related issues are usually straightforward to diagnose.
Invalid Refresh Token
The token may have expired, been revoked, or already been replaced through token rotation.
The client typically needs to restart the OAuth authorization flow.
Refresh Token Reuse
If token rotation is enabled, attempting to reuse an older Refresh Token usually causes the request to fail.
This behavior helps detect stolen credentials.
Missing offline_access
Some Authorization Servers issue only Access Tokens unless the appropriate scope has been requested.
Revoked User Consent
If a user removes the application's authorization, previously issued Refresh Tokens become invalid.
The user must grant access again before new tokens can be issued.
Security Best Practices
Refresh Tokens are among the most sensitive credentials in an OAuth deployment.
Follow these recommendations whenever possible.
Store Refresh Tokens Securely
Treat Refresh Tokens like passwords.
They should never be exposed to client-side JavaScript, log files, or version control.
Use HTTPS Everywhere
All communication involving Refresh Tokens should occur over encrypted HTTPS connections.
Prefer Token Rotation
If supported by the Authorization Server, Refresh Token rotation significantly improves security.
Never Send Refresh Tokens to MCP Servers
Refresh Tokens belong exclusively to the Authorization Server.
Only Access Tokens should be included in requests sent to MCP servers.
Handle Revocation Gracefully
Applications should expect Refresh Tokens to become invalid and provide a smooth path for users to authenticate again when necessary.
Want to analyze your API security?
Import your OpenAPI spec and generate a Security Report automatically.
Conclusion
Refresh Tokens make long-running OAuth sessions practical without sacrificing security.
Instead of extending the lifetime of Access Tokens, OAuth allows clients to securely obtain new Access Tokens whenever needed. This approach reduces login interruptions while limiting the risk associated with leaked credentials.
For MCP clients such as Cursor and Claude Code, Refresh Tokens enable seamless access to remote MCP servers, while keeping authentication responsibilities separated from resource access. Combined with short-lived Access Tokens, token rotation, HTTPS, and secure storage, they form a key part of a modern OAuth security architecture.
Continue learning:
- OAuth Bearer Tokens for MCP — Learn how Access Tokens authenticate requests.
- OAuth PKCE for MCP — Understand how PKCE secures the Authorization Code flow.
- MCP OAuth — Explore OAuth authentication in the Model Context Protocol.
- Cursor MCP Authentication — Learn how Cursor authenticates with remote MCP servers.
- Cursor MCP Permissions — Understand authorization after authentication.
- OAuth 2.1 MCP — Dive deeper into the OAuth 2.1 model used by MCP.