# Gjalla MCP Server - Query Examples

> Examples of queries AI coding agents can make to Gjalla's Model Context Protocol (MCP) server

## Available MCP Tools

### Discovery Tools

#### `discover_projects`
Get list of projects available to this API key.

**Query:**
```json
{
  "tool": "discover_projects"
}
```

**Response:**
```json
{
  "projects": [
    {
      "projectId": 123,
      "name": "E-commerce Platform",
      "repoUrl": "github.com/acme/platform",
      "lastAnalyzed": "2026-01-18T10:30:00Z"
    }
  ]
}
```

---

#### `get_context`
Project state. Call this first in every session. With no args, returns an overview (entry counts, metadata, rule summary). Pass a `scope` to drill into a primitive: `architecture | tech_stack | capabilities | data_model | rules | system`. Pass a `path` for dot-notation drill-down (e.g. `architecture.elements.api-server`).

**Query (overview):**
```json
{
  "tool": "get_context"
}
```

**Query (architecture scope):**
```json
{
  "tool": "get_context",
  "scope": "architecture"
}
```

**Response:**
```json
{
  "containers": [
    {
      "elementId": "web-app",
      "name": "Web Application",
      "type": "container",
      "description": "React SPA serving customer-facing UI",
      "technology": "React 18, TypeScript, Vite"
    },
    {
      "elementId": "api-gateway",
      "name": "API Gateway",
      "type": "container",
      "description": "Express REST API handling authentication, routing",
      "technology": "Node.js, Express, PostgreSQL"
    }
  ],
  "relationships": [
    {
      "from": "web-app",
      "to": "api-gateway",
      "type": "calls",
      "protocol": "HTTPS/REST"
    }
  ],
  "principles": [
    {
      "id": "principle-1",
      "name": "API-First Design",
      "description": "All features exposed via REST API before UI implementation"
    }
  ],
  "decisions": [
    {
      "id": "adr-003",
      "title": "Use PostgreSQL for Primary Database",
      "status": "accepted",
      "decision": "PostgreSQL chosen for ACID guarantees and JSON support"
    }
  ]
}
```

---

#### `get_source_of_truth_doc`
Fetch canonical docs or codebase context.

**Query:**
```json
{
  "tool": "get_source_of_truth_doc",
  "projectId": 123,
  "type": "architecture"
}
```

**Response:**
```json
{
  "contextType": "architecture",
  "metadata": {
    "source": "analysis_artifact",
    "format": "text"
  },
  "content": "# Architecture Overview\n..."
}
```

---

#### `get_context` (capabilities scope)
Query what your system can actually do, with code-level proof.

**Query:**
```json
{
  "tool": "get_context",
  "scope": "capabilities",
  "path": "capabilities.user_management"
}
```

**Response:**
```json
{
  "capabilities": [
    {
      "capability_id": "cap-user-registration",
      "capability_name": "User Registration",
      "category": "user_management",
      "feature": "authentication",
      "status": "active",
      "acceptance_criteria": [
        "Email validation required",
        "Password minimum 8 characters",
        "Email confirmation sent on signup"
      ],
      "evidence": {
        "implementation_files": [
          "server/services/UserService.ts",
          "server/api/auth/signup.ts"
        ],
        "test_files": [
          "server/tests/services/UserService.test.ts"
        ]
      }
    }
  ]
}
```

---

#### `get_context` (rules scope)
Get decisions, principles, and invariants that constrain implementation.

**Query:**
```json
{
  "tool": "get_context",
  "scope": "rules"
}
```

**Response:**
```json
{
  "rules": [
    {
      "id": "adr-005",
      "ruleType": "adr",
      "name": "No Direct Database Access from API Layer",
      "description": "All database operations must go through the storage layer",
      "status": "accepted",
      "rationale": "Maintain separation of concerns and enable easier testing",
      "applicableFilePatterns": ["server/api/**/*.ts"]
    }
  ]
}
```

---

## Common Agent Workflows

### Before Implementing a Feature
1. `get_context` - Orient on overview and current state (call this first)
2. `get_context` with `scope: "rules"` - Understand constraints (decisions, principles)
3. `get_context` with `scope: "architecture"` - Understand where new code should fit

### Before Modifying a File
1. `get_file_context` - Architecture elements the file belongs to and applicable rules
2. `get_impact` - Touched elements and triggered rules for the change

### Before Committing
1. `get_impact` - Touched elements, triggered rules, and unmapped files
2. `prepare_attestation` - Draft, then write the commit attestation

### After Implementation
1. Gjalla automatically analyzes commits and PRs
2. GitHub check shows architecture impact
3. Change receipts track system evolution

---

## Integration

### Claude Code / Cursor / Codex / Windsurf
Run the setup command, which auto-detects your editor and writes the right MCP config:
```
gjalla setup mcp
```

Or add it manually (Claude Code, `.mcp.json`):
```json
{
  "mcpServers": {
    "gjalla": {
      "command": "gjalla",
      "args": ["mcp", "serve"]
    }
  }
}
```

The MCP server reads from `.gjalla/config.yaml`, so no API key is needed in the MCP config itself.

### Hosted MCP endpoint
The hosted streamable-HTTP MCP transport is available at:
```
POST https://gjalla.io/mcp/stream
Authorization: Bearer {gja_api-key}
```