gcontext

The workspace your agent works in: tasks it tracks, integrations it operates, scripts it runs. Structure lives in the cloud so every session starts oriented; secret values and script execution never leave your machine.

One prompt like "ship the launch discount: new payment link in Stripe, point promo.example.com at the site, update the launch task" and your agent reads the integration docs, runs the scripts locally with keys injected from your local secret store, and checks off the task, without a single key entering the conversation.

Get started (2 minutes)

uvx gcontext-mcp login   # browser sign-in at https://app.gcontext.ai mints a token

Then add it to Claude Code:

claude mcp add-json gcontext '{
  "type": "stdio",
  "command": "uvx",
  "args": ["gcontext-mcp"],
  "env": { "GCONTEXT_TOKEN": "<your token>" }
}'

Free up to 30 files, no credit card. Needs uv/uvx on your PATH.

What your agent gets

• Tasks: typed folders with goals, steps, and progress notes the agent maintains, so the next session picks up exactly where the last one stopped.
• Integrations: docs per third-party service (what it is, allowed/never operations, which secret NAMES it needs) that act as the agent's operations manual and guardrails.
• Local script execution: tool_run_script runs Python on YOUR machine with secret values injected from ~/.gcontext/.env (chmod 0600; OS keychain opt-in via GCONTEXT_SECRET_BACKEND=keychain) and scrubbed from every output the agent sees.
• A secret-name registry: the cloud knows only NAMES and descriptions; values are filled once via a local browser form and stay on your machine.

The privacy split

Why: pasting API keys into a chat is how keys end up in logs and screenshots, and a cloud that executes your code with your keys HAS your keys. gcontext gives the agent full operational ability with zero key custody.

Other clients and modes

Claude Desktop (no CLI): edit the config file (Settings → Developer → Edit Config; macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json), then fully restart:

{
  "mcpServers": {
    "gcontext": {
      "command": "uvx",
      "args": ["gcontext-mcp"],
      "env": { "GCONTEXT_TOKEN": "<your token>" }
    }
  }
}

Keep the server name gcontext (or change it in the dashboard's Settings); every prompt the dashboard copies references the server by that name. Desktop has no slash-command prompts (/use-integration, etc.); you drive the same tools by plain chat.

Self-hosting: same product, your server, one docker compose up and a single token. See SELF_HOSTING.md or https://gcontext.ai/self-hosting.

Pure-local dev (no cloud, own SQLite), from a checkout:

claude mcp add gcontext -- uv run --directory /ABS/PATH/TO/apps/mcp-minimal python server.py

Tools

• tool_list_dir(path="/"), tool_read_file(path), tool_write_file(path, content), tool_delete(path) — tool_write_file auto-creates missing parent folders
• tool_secrets(action="list"|"register"|"unregister", name, description), tool_setup_secrets(form=True)
• tool_run_script(code) - runs Python locally with secrets injected from the local store (~/.gcontext/.env by default)

The secret registry

The registry holds secret NAMES + descriptions only — it is for setup and verification, not runtime. It does NOT gate tool_run_script, which injects the whole secret environment from the local store regardless of what's registered.

1. tool_secrets(action="register", name, description) - declare a required secret.
2. tool_setup_secrets() - opens a local browser form where the user fills in the values; they are stored in ~/.gcontext/.env (chmod 0600), or the OS keychain with GCONTEXT_SECRET_BACKEND=keychain (form=False appends blank NAME= lines to the .env instead).
3. tool_secrets() - shows present per name so you can confirm setup.

How it works

1. Write a file describing a 3rd-party operation and which secret NAMES it needs; declare those names with tool_secrets(action="register").
2. To act, read the file, generate Python, and call tool_run_script.
3. Secret values resolve from the local store (~/.gcontext/.env by default, keychain opt-in) at run time - never stored in the DB.

Security / trust model

tool_run_script runs arbitrary Python locally with your real secret values injected - there is no sandbox. It is exactly as trusted as whatever drives the server. Run it on your own machine only; never expose this server remotely.

Script contract

• Read secrets via os.environ["VAR"] - never hardcode, never load_dotenv.
• Use only registered names that show present_locally: true.
• Exit codes: 0 OK, 2 missing secret (KeyError), 1 any other failure.

Config (env vars)

• GCONTEXT_API_URL - backend origin (default https://app.gcontext.ai; set for self-host).
• GCONTEXT_TOKEN - the dashboard-minted token.
• MCP_MINIMAL_DB - SQLite path for pure-local mode (default db.sqlite next to server.py).
• MCP_MINIMAL_ENV_FILE - secret-values file (default ~/.gcontext/.env).
• GCONTEXT_SECRET_BACKEND - env (default: values in the 0600 .env) or keychain (OS keychain).

Developing

Tests and the three-ring test architecture: see tests/README.md. Run everything with make test.