Use Gheima with AI

Connect Claude, Cursor, VS Code or any MCP client to your account, and give coding agents the docs in Markdown.

View as Markdown Open in Claude Open in ChatGPT

Gheima works with AI assistants and coding agents in three ways: a hosted MCP server that lets an assistant see and act on your account, every docs page as Markdown, and a CLI whose --json output and exit codes are built for scripts.

Connect an assistant (MCP)#

Add https://gheima.ma/mcp as a remote MCP server. The first time, your browser opens a Gheima sign-in where you choose read only or read and write. The assistant receives an API key for exactly that. It is listed in Settings → API keys as MCP: <app name>, and revoking it there disconnects the assistant.

Shell

claude mcp add --transport http gheima https://gheima.ma/mcp

Claude Code. In Claude on the web or desktop: Settings → Connectors → Add custom connector, then paste the URL.

JSON

{ "mcpServers": { "gheima": { "url": "https://gheima.ma/mcp" } } }

Cursor: ~/.cursor/mcp.json

JSON

{ "servers": { "gheima": { "type": "http", "url": "https://gheima.ma/mcp" } } }

VS Code: .vscode/mcp.json

Only an owner or admin can connect an assistant, because connecting creates an API key.

Run it locally#

The same server runs on your machine over stdio, with the key gheima login saved. Use it when you want the assistant to read credentials, which the hosted server never does.

JSON

{ "mcpServers": { "gheima": { "command": "npx", "args": ["-y", "@gheima/mcp"] } } }

Locally, tools that change anything are refused unless you start the server with GHEIMA_MCP_ALLOW_WRITES=1. Reading credentials (revealing a database password, running SQL) also needs GHEIMA_MCP_ALLOW_SECRETS=1, and a confirmation on each call.

What the assistant can do#

See services, deployments, logs and metrics, and explain a failed deploy.
Deploy, restart, pause, resume and scale a service.
List databases, take snapshots, and browse storage buckets.
Read and run cron jobs.
Check usage, the current bill, domains, alerts and the audit log.
Reach every other API operation through one general tool. Deleting, rotating or resetting anything needs an explicit confirmation.

The server also offers ready-made prompts (Why did my deploy fail?, How is my service doing?, What will this month cost?) and serves these docs to the assistant, so it can look up how something works before it acts.

Everything an assistant does is recorded in the audit log under the MCP surface, so you can tell its actions from yours.

Docs for models#

/llms.txt: An index of every docs page with a one-line summary.
/llms-full.txt: Every docs page in one plain-text file.
/docs/<page>.md: Any docs page as Markdown. Add /fr or /ar before /docs for French or Arabic.
Accept: text/markdown: Request a docs page with this header to get the same Markdown at its normal URL.
/api/v1/openapi.json: The OpenAPI 3.1 spec for the REST API.

Tell your coding agent how you deploy#

Coding agents read AGENTS.md at the root of a repository. gheima agents prints a short Gheima section for it: the service this folder deploys to, how to deploy and read logs, and the exit codes. Add --write to append it to AGENTS.md. It is added once, between markers, so running it again only refreshes the section.

Shell

gheima link my-app
gheima agents --write

Run it in the folder you linked. Claude Code reads CLAUDE.md, so add a line @AGENTS.md there to share the same file.

Discovery for agents#

/.well-known/mcp/server-card.json: How to reach the hosted MCP server.
/.well-known/oauth-protected-resource: Where an MCP client signs in (RFC 9728).
/.well-known/api-catalog: Links to the API spec and its docs (RFC 9727).
/.well-known/agent-skills/index.json: A skill that teaches a coding agent to deploy on Gheima.