MCP server

What is the gjalla MCP server?

The gjalla MCP server wraps the CLI and lets AI coding agents (Claude Code, Cursor, Codex, etc.) query your project’s state, rules, and architecture context. Instead of generating code in isolation, agents can understand architecture, check constraints, and evaluate impact.

The MCP server reads from the same local cache as the CLI. No separate configuration or API keys needed beyond what gjalla setup already configures.

MCP (Model Context Protocol) is a standard for connecting AI agents to external context sources.

There are two ways to connect: the hosted MCP server (a URL, no install) and the local MCP server (runs via the CLI on your machine). Both expose the same tools.

Hosted MCP: connect by URL

The hosted server is the fastest way in, and the only option for browser-based and managed agents (Claude.ai, Lovable, ChatGPT) that can’t shell out to a local CLI. Add this URL anywhere your tool accepts a remote MCP server:

https://app.gjalla.io/mcp/stream

Per-host setup

• Claude.ai: Settings → Integrations (or Connectors, depending on plan) → add a custom MCP server with the URL → approve the OAuth request.
• Claude Code: claude mcp add --transport http gjalla {hostedMcpUrl}, then /mcp to authenticate.
• Cursor: Settings → Features → MCP (or edit ~/.cursor/mcp.json) → add a server with the URL → choose OAuth and approve in the popup.
• Lovable: Settings → Integrations → Custom MCP → paste the URL → Connect → approve in the gjalla popup.
• ChatGPT: open custom-connectors / MCP settings (visibility depends on plan) → add a connector with the URL → approve the OAuth request.

Authentication

OAuth is the default and recommended method: the host opens a gjalla approval popup and receives a short-lived key automatically. Hosts that support pasting a bearer token can use a gjalla API key (gja_...) instead; paste it into the host’s bearer-token field, never into the URL.

Manage and revoke connected hosts anytime under Settings → Integrations. Revoking takes effect immediately.

If you’re an agent, start here

You’re an AI coding agent. Here’s the short version of where, why, and how to use gjalla.

Session-start protocol

First thing in any session, before you start exploring or editing:

get_context()                         # what this project is, in 2-5 KB
get_findings(since="7d")              # what's currently flagged + the synthesis-curated attentionItems shortlist
# Then, before editing any file:
get_file_context(file_path="...")     # which elements it belongs to, which rules apply

That’s the wake-up routine. Run it once per session and you have the orientation you’d otherwise build up over 5-10 grep and read calls. get_findings is especially valuable: each runs[] entry includes an attentionItems[] shortlist (typed risk | watchlist | follow-up) that the synthesis agent has already curated for you. That’s where to look first if your job is to triage and fix.

Intent → tool

Match your current intent to the right tool. The full reference is below; this is the shortcut.

• Orient on a new project / resume a session → get_context() + get_findings(since="7d")
• About to edit a file → get_file_context(file_path="...")
• About to design a change → get_context(scope="rules") + get_context(scope="architecture")
• Triaging or fixing flagged issues → get_findings() (read runs[].attentionItems first), then get_file_context on the touched files
• Investigating recent change / weird behavior → get_changes(since="7d") + get_findings(since="7d")
• Before committing → get_impact(), then prepare_attestation() (draft) → prepare_attestation(...) (write)
• Stuck / empty results → get_status() (config check) or sync() (refresh cache)

Why it’s cheaper than exploring

One get_context(scope="architecture") call returns a digested fact list (element names, roles, key relationships) in ~2-5 KB. The equivalent exploration is reading 5-10 source files (~50 KB+) and grepping for patterns. Same for rules: one call returns the active constraints; the exploration alternative is finding and reading ADR files. If you’re optimizing for tokens or for getting it right the first time, the gjalla call wins.

What gjalla knows that you don’t

gjalla holds the things no single file can tell you:

• Architecture facts: what each element does, how they connect, which ones are unstable. Derived from analysis, not from comments in code.
• Rules and ADRs: constraints other engineers wrote down. You’ll violate them silently otherwise.
• The intent / reality gap: what was specced vs what actually shipped. Drift findings surface this; agents don’t intuit it from source code alone.
• Cross-session memory: what your past sessions (and other agents’ sessions on this project) learned. Read through get_memories()
• Curated attention: the synthesis agent’s ranked shortlist of what matters right now (attentionItems on get_findings).

Attestation: how you prove you did it right

When you commit, gjalla expects an attestation. This isn’t paperwork. It’s the artifact that lets your human collaborator trust your work without re-reading every line. You’re telling them, on the record: I checked these rules, I touched these architecture elements, and here’s the impact.

The attestation workflow closes a loop you should already be running mentally. Two MCP calls and a write:

# 1. Read the rules so you actually know what to attest against.
get_context(scope="rules")

# 2. Compute the blast radius: which elements you touched, which rules apply.
get_impact()

# 3. Draft the attestation (gjalla pre-fills staged files, affected elements,
#    applicable rules, diff hash, and a template for you).
prepare_attestation()

# 4. Write the final attestation with your self-reported rule status and
#    summary of architectural impact.
prepare_attestation(
    summary="...",
    rules={"checked": True, "applicable": [...]},
    changes={...},
)

What this gets you as an agent: your work becomes legible. The human reviewing the PR can see at a glance which rules you considered (and whether you flagged anything as remediated or needs-review), which architecture elements moved, and why. Reviews go faster and your trust budget with the team grows over time. The pre-commit hook also catches violations locally so you don’t learn about them from a failed CI run an hour later.

Be honest in the attestation. If you couldn’t determine compliance with a rule, mark it needs-review with a short note. That’s what humans want to see, not a blanket compliant that turns out to be wrong.

Local MCP server: via the CLI

If you have the gjalla CLI installed, this is the fastest way to get set up:

gjalla setup mcp

This auto-detects your editor and writes the MCP config for you. If gjalla is installed locally with the mcp extra, it uses the local binary directly. Otherwise it falls back to uvx for zero-install.

Manual setup by tool

If you prefer manual setup, add the config below. No API key or env vars needed in the MCP config. The server reads from .gjalla/config.yaml.

{
  "mcpServers": {
    "gjalla": {
      "command": "gjalla",
      "args": ["mcp", "serve"]
    }
  }
}

### Architecture and System Design
Always check with gjalla to get context on the system to orient you, guidance on architecture, prior decisions, principles that must be adhered to, etc.

Use `gjalla rules show` and `gjalla state show` (CLI) or the gjalla MCP tools to review project state before implementing. Report any additions, removals, or modifications to state entries in your attestation.

{
  "mcpServers": {
    "gjalla": {
      "command": "gjalla",
      "args": ["mcp", "serve"]
    }
  }
}

### Architecture and System Design
Always check with gjalla to get context on the system to orient you, guidance on architecture, prior decisions, principles that must be adhered to, etc.

Use `gjalla rules show` and `gjalla state show` (CLI) or the gjalla MCP tools to review project state before implementing. Report any additions, removals, or modifications to state entries in your attestation.

{
  "mcpServers": {
    "gjalla": {
      "command": "gjalla",
      "args": ["mcp", "serve"]
    }
  }
}

### Architecture and System Design
Always check with gjalla to get context on the system to orient you, guidance on architecture, prior decisions, principles that must be adhered to, etc.

Use `gjalla rules show` and `gjalla state show` (CLI) or the gjalla MCP tools to review project state before implementing. Report any additions, removals, or modifications to state entries in your attestation.

Using uvx (no local install)

If gjalla isn’t installed locally, use uvx instead:

{
  "mcpServers": {
    "gjalla": {
      "command": "uvx",
      "args": ["--with", "gjalla[mcp]", "gjalla", "mcp", "serve"]
    }
  }
}

Available MCP tools

Context & discovery

Impact & attestation

Change history

Deep exploration

Skills & memories

Cross-project (systems)

Management

Choosing a scope

add_rule, add_skill, and save_memory all take the same scope / scopeId pair, so pick by who the thing is actually for. A team-wide standard belongs at team scope rather than copied into each codebase.

• Team — scope="team". Omit scopeId and it targets the team on your credential, so you never need a lookup call first. Requires team-admin.
• System — scope="system" with an explicit scopeId.
• Project — the default. Uses the connected project unless you pass a scopeId.
• Personal — local server only, when signed out. Writes to ~/.gjalla/user/ and never reaches the network.

Resolution runs lowest to highest: platform, then team, then system, then project, with the more specific scope overriding.

CLI equivalents

The MCP server wraps the CLI. Agents can use either; the CLI is faster for simple lookups.

• get_context() → gjalla state show
• get_context(scope="rules") → gjalla rules show
• get_context(scope="architecture") → gjalla state show -c architecture
• get_file_context(file_path="...") → gjalla state context -f "..."
• get_impact() → gjalla state impact
• get_changes(since="7d") → gjalla log --since 7d
• get_project_skills() → gjalla skills show
• sync() → gjalla sync