Gagarin Cloud MCP server

mcp

mcp.gagarin.cloud — gagarin's API, as tools an agent can call.

npm install
npm run build
npm test                 # builds, then node --test over dist/
npm start                # the HTTP server on :8080
npm run stdio            # the same tools over a pipe

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:

Signing in

Remote, with OAuth. Give the client the URL and nothing else:

https://mcp.gagarin.cloud/mcp

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. GAGARINMCPORIGIN and GAGARINISSUER override the two public names for a development setup; they are separate from GAGARINAPI, 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.

{
  "mcpServers": {
    "gagarin": {
      "type": "http",
      "url": "https://mcp.gagarin.cloud/mcp",
      "headers": { "Authorization": "Bearer <your gagarin credential>" }
    }
  }
}

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.

What is here

It is a translator, and nothing else

Shortened. The full README is on GitHub.