Inside the platform
An MCP server that worked on Monday and reads disconnected on Tuesday has usually not failed at all. Something around it did: a renewal that never ran, a refresh token that was thrown away, a token endpoint that moved, a grant that quietly expired. Those are four different faults with four different fixes, and a platform that treats them as one - retry everything - makes each of them worse. This is what we learned keeping a fleet of these connections alive, written as standards reasoning and observable behaviour so it is useful whichever platform you run.
Most MCP servers that need a sign-in use OAuth. The sign-in produces a short-lived access token, which the agent presents on every call, and a longer-lived refresh token, which is used to obtain a new access token when the first runs out. An agent that never calls the server between renewals still has to renew, and that is where most of the trouble starts: the interesting failures happen when nobody is watching.
The symptom is always the same word on a status pill. The causes are not, and the correct response to each is different enough that confusing them is itself a failure mode. A timeout wants patience. A moved endpoint wants rediscovery. A dropped refresh token wants a client that never drops one. A lapsed consent wants a person, and nothing else will do.
Each has a different fix. None is the MCP server's fault, and none is specific to any one provider - the standards permit all of it.
The standard makes a new refresh token optional in a renewal response. A client that stores the response verbatim overwrites the token it had with nothing, and the next renewal - an hour later, typically - has nothing to present.
The client cached where to send renewals, or guessed when discovery came back empty. When that address answers 404, a naive client reads it as a refused grant and deletes tokens nobody rejected.
The agent started, the server was slow or down, the connection timed out, and nothing came back later to try again. A short outage on their side became a permanent gap on yours.
The provider expired or revoked the grant, or the sign-in was never completed for this server on this agent. No amount of reconnecting fixes this, and a platform that keeps trying is hiding the real state.
This is the most common way we have seen a working connection die, and it sits entirely within the letter of the standard. Section 6 of RFC 6749 says the authorisation server may issue a new refresh token when it renews an access token, and section 5.1 lists refresh_token as optional in the response. Two provider behaviours follow, and both are compliant: some rotate the refresh token on every renewal and invalidate the old one; others issue one refresh token at sign-in and never send another.
A client written against the first kind stores whatever the renewal returns. Against the second kind that means storing a fresh access token and an empty slot where the refresh token used to be. Nothing fails yet - the new access token is good for an hour or so. Then it expires, the client goes to renew, finds no refresh token, and the connection is dead. From the outside it looks as though the provider dropped you an hour after everything worked, which is why this one is so hard to diagnose from the symptom alone.
The rule is short. When a renewal response omits the refresh token, keep the previous one, and treat the granted scope the same way. A client that does this survives both kinds of provider without needing to know in advance which kind it is talking to.
The second trap is about reading errors. Section 5.2 describes what a refused token request looks like: an HTTP 400 response in the ordinary case, carrying an error code such as invalid_grant. That is the shape of a refusal the standard defines, and a 404, a 405 or a 410 is not it. Those responses say the request never reached a token endpoint at all - because discovery returned nothing and the client fell back to a conventional path, or because the provider moved the endpoint after the client had cached it.
Clearing stored tokens on that response destroys a refresh token nobody refused, and turns a routing problem into a fresh sign-in for a human. The right reaction is to keep the grant, forget the cached endpoint and whatever metadata produced it, run authorisation server discovery again, and renew against the address it now advertises. Olano does this: when the token endpoint it had stops answering, it rediscovers the provider's endpoint and renews with no human involved.
The common design renews lazily: the next time the agent calls a tool, the client notices the access token has expired and renews on the way. It is simple, and it works for a busy agent. It fails for an idle one. An agent with nothing to do over a weekend makes no calls, so no renewal fires, and by the time one does the refresh token itself may have passed whatever lifetime or inactivity limit the provider applies. At that point the grant is unrecoverable and a person has to sign in again, for a connection that was never actually used.
Renewal has to run on a clock, from a periodic check, and it should be a direct request to the token endpoint rather than something that piggybacks on a tool call. That distinction matters more than it looks. In the MCP authorisation model the MCP server is a resource server and tokens come from an authorisation server, which may be a different service at a different address. A direct renewal can succeed while the MCP server itself is down, so the grant is still good when the server comes back.
Olano renews stored grants on a periodic check, ahead of expiry - by default about twenty minutes before, with the window adjustable. Renewal is on by default and the guidance is to leave it on: a token that lapses while the agent is idle can become unrecoverable.
Every case above can be fixed by software. One cannot. When a server needs a sign-in the agent has never been given, or a grant the provider has expired or revoked, the only fix is a person clicking Authorise. Reconnecting cannot invent consent.
That sounds obvious and it is routinely got wrong, because the easy design treats every failed connection as retryable. A platform that puts a consent-needed server on the same retry schedule as a timed-out one rebuilds that agent's tools on a timer forever, achieves nothing on every attempt, and - worse - reports "reconnecting" when the honest status is "waiting for you". Olano never retries a server that needs consent it does not have. It raises a notification on the bell and on Overview naming the server and the agent, with a link straight to that agent's MCP tab, and the notification says plainly that reloading will not fix this one. There is one row per agent per server, since each agent authorises its own servers, and the row clears itself the moment the server connects.
What each failure means and what should happen next. The last two rows are the ones a generic retry loop gets wrong.
| What you see | What it usually means | What a platform should do |
|---|---|---|
| Timed out at boot | The server was slow or down when the agent started. | Retry with exponential backoff, spacing attempts out, so a server that is down for an hour is not hit every few seconds and one that recovers is picked up without a restart. |
| Connection error | A transient fault on the network or on the server. | The same backoff schedule. An explicit reload from the MCP tab should always override it - a person pressing the button must never wait for the schedule. |
| Token endpoint answers 404, 405 or 410 | The renewal never reached a token endpoint. | Keep the grant. Discard the cached endpoint and metadata, rediscover, renew again. |
| 400 with invalid_grant | The provider refused the refresh token: expired, revoked, or already rotated. | Stop renewing. Tell a person which server, on which agent, needs re-authorising. Do not retry. |
| Sign-in required, no token stored | Consent was never given for this server on this agent. | Never retry. Show the state honestly and wait for a person. |
You should never have to read a log to learn a connection is down, and you should never learn it from the agent failing at a task.
The agent's MCP tab shows each server's live status and sign-in state, with an expiry-aware token pill that turns red and offers Re-authorize rather than pretending an expired token is fine.
Config → MCP connection health shows every server on every agent in one place, so "is anything down" is one page rather than a tour.
A grant that can no longer be renewed goes on the bell, naming the server and the agent, linking to the fix, and clearing itself when the server connects.
/mcps in a conversation reports the state of the agent's servers, so the person talking to the agent can check without opening the dashboard.
Reload agent swaps a newly authorised server's tools into the running agent, and an explicit reload always wins over the automatic retry schedule.
Add the server before you sign in. A sign-in completed for a URL the agent does not yet have looks successful and leaves a grant for a server the agent will not load. Olano registers such a server from the sign-in itself, but adding it first, with the settings you actually want, is still the right order.
Keep secrets in the vault, not the config. A server that wants an OAuth app of your own takes the client ID on its entry and the client secret as a ${vault:NAME} reference; a later reconnect never asks for either again. The same reference works for an API key in a header.
Leave renewal on. It is on by default, and a grant that lapses on an idle agent is the one failure that costs a person's time to recover.
Authorise per agent. Each agent authorises its servers independently, so two agents can hold different grants for the same service, and one needing re-authorisation says nothing about the other.
If you run the box yourself, keep it awake through the renewal window. Everything above assumes something is running when the clock says renew. A laptop asleep through that window can wake to a connection that needs a person, and it was not the provider's doing.
Olano can also be the server. An agent published over MCP for outside callers signs them in with Olano's own OAuth 2.1 flow, and there the choices are made deliberately: refresh tokens rotate on every renewal, and a client may keep renewing for a set number of days before it needs a fresh consent. If you are building a client against it, everything on this page applies to you in reverse.
The commonest cause is a dropped refresh token. The OAuth standard makes a new refresh token optional in a renewal response, so a client that saves the response verbatim can overwrite the refresh token it had with nothing. The new access token works until it expires, usually about an hour, and the next renewal then has nothing to present. The fix is a client that keeps the previous refresh token whenever a response omits one.
Usually not. Either the client discarded the token on an earlier renewal, or the renewal was sent to an address that is no longer a token endpoint and the client wrongly treated the 404 as a refusal, or the grant genuinely expired or was revoked because nothing renewed it while the agent was idle. Only the last needs a person to sign in again; the first two are client-side faults.
No. Reconnecting cannot invent consent. A server that needs a sign-in you have not given, or a grant the provider has expired or revoked, needs a person to authorise it again. Olano never retries that case; it raises a notification naming the server and the agent with a link to the MCP tab, and the notification says that reloading will not fix it.
On a clock, ahead of expiry, with a direct request to the provider's token endpoint - not lazily on the next tool call, which never comes for an idle agent. Keep the previous refresh token when a renewal omits one. Treat a 404 from the token endpoint as a moved endpoint to rediscover, not a refused grant. Retry timeouts and errors with backoff, and never retry anything that needs consent.
That the renewal request did not reach a token endpoint. RFC 6749 describes a refused token request as an HTTP 400 response carrying an error code such as invalid_grant; 404, 405 and 410 are not among the responses it defines, and mean the address was wrong or has moved. The right response is to keep the stored grant, discard the cached endpoint, run discovery again and renew at the new address.
On the agent's MCP tab for one agent, under Config → MCP connection health for the whole deployment, or by sending /mcps in a chat. A grant that needs re-authorising also raises a notification on the bell and on Overview with a link to the agent's MCP tab, one row per agent per server, which clears when the server connects.
Where to go next.
Adding an MCP server, the guided Connect form, per-tool switches and Reload agent.
The same OAuth rules from the server's side, with Olano signing in outside callers.
The renewal window on a machine that was asleep, diagnosed.
Keeping connections alive is one of the five things unattended work depends on.
Checked 14 September 2026. The standards cited are RFC 6749, RFC 8414 and the MCP authorisation specification, linked inline; provider behaviours are described in general terms because both patterns described are compliant. If we have described something wrongly, write to support@olano.ai and we will correct this page.
Tell us which MCP server it is and what the status pill says. We will tell you which of the four faults it is, and whether it is something a platform should have handled or something only you can.
