The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gagarin Cloud listing page.
mcp.gagarin.cloud — gagarin's API, as tools an agent can call.
The Model Context Protocol is how an agent finds and calls a tool it was not built with. This is gagarin's, and it exists so that adding gagarin to a coding agent is a URL rather than an install — the one artefact that makes the platform installable rather than merely documented.
Two ways in, one implementation:
| remote | https://mcp.gagarin.cloud/mcp, streamable HTTP, credential in the Authorization header — put there by OAuth sign-in or by hand |
| local | npm run stdio from a clone of this repository, credential from GAGARIN_TOKEN or the file gg login wrote — for developing on this server, not a way to install it |
Remote, with OAuth. Give the client the URL and nothing else:
Claude, ChatGPT and Claude Code prompt for sign-in when they connect: the client
opens a browser and the human signs in with GitHub or Google. A request with no
credential answers 401 with a WWW-Authenticate header pointing at
/.well-known/oauth-protected-resource/mcp, which names api.gagarin.cloud as
the authorization server. This server decides nothing about a token itself; the
engine does, on every call. GAGARIN_MCP_ORIGIN and GAGARIN_ISSUER override the two public
names for a development setup; they are separate from GAGARIN_API, which in
the cluster is the in-cluster Service and no address a client could sign in at.
Remote, with a credential in a header. For a client that cannot sign in
over OAuth, or a machine that should not: a credential from gg login or
gg creds create.
Local, over stdio. npm run stdio from a clone runs the same tools over a
pipe, reading the file gg login wrote, or GAGARIN_TOKEN if it is set. It is
here to develop against, and is deliberately not published to npm: the point of
this server is that adding gagarin to an agent is a URL and not an install, and
a package on somebody's laptop is a second copy of src/tools.ts that goes
stale the day a tool changes.
A credential that has expired or been revoked is caught at the door too, because
a client signs in again only on an HTTP 401: every POST asks the engine
/v1/whoami with the caller's token first, and the engine's 401 becomes a 401
with error="invalid_token". One extra in-cluster call per request, and no
cache — a remembered token is a stored token, and this server stores none. Any
other failure there (the engine unreachable, a 5xx) is not a sign-in problem, so
the request goes on and each tool reports it with the engine's own code.
| path | what it is |
|---|---|
src/api.ts | the whole of this server's contact with gagarin: one request, one error envelope |
src/tools.ts | every tool — each one a path, a shape, and the rule a caller needs before using it |
src/server.ts | what a client is told on connect, and the gagarin://guide resource — including how memory is used and the .gagarin.json note that says which project a repository is |
src/app.ts | mcp.gagarin.cloud: stateless streamable HTTP, one server per request, and the OAuth protected-resource metadata |
src/http.ts | the listener, its configuration and its drain |
src/stdio.ts | the same tools over a pipe, for developing against from a clone |
src/credentials.ts | reads the credential file gg login wrote; never writes one |
Dockerfile | the image mcp.gagarin.cloud runs. Its build stage runs the tests |
Every project carries a memory: small, durable facts an agent saves about a
codebase — a decision and why, a convention, a gotcha — so the next session does
not rediscover them. It is a built-in of the project, like its registry, and
these tools are the only way to reach it: the memory service has no address
of its own, no gg command and no console page. The engine decides who may
read (viewer) and who may write (editor), on every call, like everything else.
| tool | what it does |
|---|---|
memory_briefing | what is known about a project, packed to a token budget — the first call on a project |
memory_search | hybrid semantic + keyword search; no query browses by rank |
memory_get | memories in full, by id |
memory_related | walk the links out from one memory |
remember | save one fact; a near-duplicate is refused with the memories it collided with |
memory_update | change fields, pin, or archive |
memory_link / memory_unlink | associate two memories, or stop |
These answer the memory service's own text — a plain-text rendering packed to
the budget — rather than the JSON around it. That is a narrower case of the rule
below, not an exception to it: the rendering is still the engine's, and returning
both would spend twice the tokens the service exists to save. A body without
text comes back as JSON like any other answer.
It holds no credential of its own, has no database, and makes no decision the
API does not make. Every tool is one call to api.gagarin.cloud carrying the
caller's own bearer token, and every refusal is the engine's refusal passed
through unedited.
That is the property everything else rests on: possessing this server grants nothing at all. It is what makes it safe to put a public endpoint in front of a single write gate, and nothing here may be changed in a way that weakens it.
Two consequences worth stating, because both look like omissions:
sentence written by the engine,
precisely so a terminal and a dashboard cannot describe the same row
differently. A third renderer here would be a third opinion to keep in step.[code] message with a hint: line, which is what gg prints.
One format, so an agent that has read the gagarin skill recognises what comes
back here without being taught a second one. When the engine sends more than
the envelope — a memory_duplicate carries the near-duplicates — that is
appended after the hint rather than dropped.Four things need a machine, and offering them here would produce failures that read like platform faults:
gg ship — build, push and deploy fused — shells
out to docker where the source is. deploy here runs an image that is
already in gagarin's registry: a tag CI pushed, or a restatement. Getting one
there is the CLI's job.gg connect binds a local port.run submits and returns a revision, like every
other write here. gg run blocks until the run ends and exits with the
script's own exit code, which is what a pipeline wants; over MCP you poll
status for the phase and the code.There is also no list of resource types, sizes or scopes in this repository. The
engine owns those and its refusals name them; a z.enum here would be a second
list in a second repository, wrong on the day a type is added — a mistake this
codebase has already made once, in gg, about this exact family of values.
In the Kubernetes cluster, next to the control plane, and not on Vercel beside the site and the console. Those two live outside Scaleway because their job is to still be there and say the platform is down. This one has nothing whatever to say when the API is unreachable; it is that API in another shape, so it belongs next to it and reaches it over the in-cluster Service rather than hairpinning out through the load balancer.
The pod runs as a ServiceAccount with no RBAC and no mounted token, on a read-only root filesystem. It needs none of them.
Every push to main builds the image and rolls it out —
.github/workflows/deploy.yml. The credentials that can do that are secrets of
the production environment, which only main may use, so a pull request never
runs next to them. Merging to main is deploying.
One server.registerTool call in src/tools.ts: a name, a description saying
the rule a caller most needs, a zod shape, and one api.call. Then a test in
src/tools.test.ts asserting the path, the method and the body — those are the
only things it is possible to be quietly wrong about, and a deploy that PUTs to
the wrong path answers 404 and reads like a missing service.
Do not add a tool for something the API does not do. This file has no business being the place a feature appears first.