Skip to main content
Documentation

Claude Code Setup Guide

Set up Minolith as an MCP server in Claude Code so your agent has access to persistent context, runbooks, changelog, feedback, and agents — all available as native tools.

Prerequisites:

  • A Minolith account (sign up — 14-day free trial, no card required)
  • A project API key (Dashboard → Settings → API Keys)
  • Claude Code installed (docs)

Step 1: Add the MCP Server

Run this command from your project directory:

claude mcp add --transport http minolith https://mcp.minolith.io \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "X-Minolith-Agent: orchestrator"

The X-Minolith-Agent header identifies which agent is making requests. This is required for task assignment (get_my_tasks) and proper attribution on notes and status changes. Use the name of the agent definition you created in Minolith.

Or add it manually to your project's .mcp.json file:

{
  "mcpServers": {
    "minolith": {
      "type": "http",
      "url": "https://mcp.minolith.io",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-Minolith-Agent": "orchestrator"
      }
    }
  }
}

Replace YOUR_API_KEY with your Minolith API key (starts with mlth_) and orchestrator with your agent's name.

Tip: Commit .mcp.json to your repo so every team member and CI environment gets the same MCP tools automatically. Your API key should be stored securely — consider using environment variables or Claude Code's persistent memory rather than hardcoding it.

Step 2: Verify the Connection

Start a new Claude Code session and check the tools are available:

/mcp

You should see minolith listed with all available tools (bootstrap, store_context, get_context, list_tags, list_scopes, etc.).

Test the connection:

bootstrap

If everything is configured correctly, you'll receive your agent identity, session instructions, and project state.

Step 3: Add a CLAUDE.md File

Create a CLAUDE.md file in your project root. This file tells Claude Code how to use Minolith at the start of every session. Below is a starter template — copy it, then customise it for your project.

Example CLAUDE.md

# CLAUDE.md

## Session Start (every conversation)

Call `bootstrap` at the start of every session. It returns your agent identity, session
instructions, high-priority context, assigned tasks, active runbook runs, feedback counts,
recent events, and follow-up suggestions. One call replaces the entire manual workflow.

After bootstrap:
1. Follow the `prompt` entries and execute any `follow_up` suggestions
2. Check `assigned_tasks` — if you have open tasks, work through them in priority order
3. Call `get_task` on your highest-priority task to load full context including notes

### Fallback (if bootstrap returns no agent)

1. `list_scopes` + `list_tags` — discover what's available
2. `get_context` with `priority=high` — load critical rules, warnings, decisions
3. `get_recent_events` with `limit=10` — recent deployments, incidents, changes
4. `get_my_tasks` — check for assigned tasks and work through them
5. `list_runs` with `status=running,paused` — check for in-progress runbook runs
6. If a run is active, call `get_current_step` and resume from where you left off
7. `get_context` with tags/scope relevant to your current task

### After Completing Work

1. `store_context` / `update_context` — persist new patterns, decisions, gotchas
2. `log_event` — record deployments, migrations, significant changes
3. If working on a task: `add_task_note` with what you did, then `update_task_status`
4. If user-facing: `create_changelog_entry`
4. If following a runbook: advance or complete the run
5. If design decisions were made: `define_tokens`, `define_component`, `define_pattern`, or `define_voice`

---

## Context Service (free — included with every project)

Use context to build a persistent knowledge base that survives between sessions.

### When to store context

After completing meaningful work, persist what you learned:

- **Rules** (`store_context` type=rule) — hard constraints that must always be followed
- **Patterns** (`store_context` type=pattern) — how things are implemented in this project
- **Decisions** (`store_context` type=decision) — architectural choices and their rationale
- **Warnings** (`store_context` type=warning) — gotchas, pitfalls, things that break
- **Facts** (`store_context` type=fact) — objective truths about the project or environment
- **Workflows** (`store_context` type=workflow) — multi-step procedures

Always include relevant `tags` and a `scope` so future sessions can find entries with targeted
queries.

### When to update or delete

- `update_context` — when an existing entry is stale or needs correction
- `delete_context` — when an entry is no longer true or relevant
- Before storing, check if a similar entry already exists to avoid duplicates

### When to log events

Call `log_event` for significant occurrences:

- Deployments (what was deployed and why)
- Migrations (what changed in the database)
- Incidents (what broke and how it was fixed)
- Configuration changes (what was changed and why)

Events are immutable — they form a timeline of what happened.

---

## Runbooks Service

Use runbooks for any multi-step workflow that should be followed consistently.

1. `list_runbooks` — find the right procedure
2. `start_run` — begin an execution with variable values
3. `get_current_step` — see what to do next
4. `advance_step` / `skip_step` / `fail_step` — progress through steps

Runbooks persist progress across sessions. If interrupted, `list_runs` with
`status=running,paused` picks up where you left off.

---

## Changelog Service

After completing user-facing work, create a changelog entry:

1. `create_changelog_entry` — log the change (title, body, category)
2. `create_changelog_version` — group entries under a version
3. `publish_changelog_entry` — make visible on the public changelog

Categories: `feature`, `improvement`, `fix`, `breaking`, `deprecation`, `security`, `other`

---

## Feedback Service

Log and manage user feedback:

- `submit_feedback` — create a new item (types: feedback, bug, idea, question, praise)
- `list_feedback` — review submissions
- `update_feedback_status` — move through workflow (new → acknowledged → planned → in_progress → resolved → closed)

---

## Styleguide Service

Define and retrieve your project's design system — tokens, components, patterns, voice rules,
and brand assets. The styleguide is returned as a summary in `bootstrap`, so agents know what
design language exists without an extra call.

### Loading the design system

- `get_styleguide` — returns the full design system (all tokens, components, patterns, voice,
  assets) in one call. Call this before building any UI.
- `get_tokens` — retrieve a specific token section (colours, typography, spacing, borders,
  shadows, breakpoints)
- `get_component` — retrieve a specific component definition by name
- `search_styleguide` — search across components, patterns, and voice entries by keyword

### Defining design tokens

Use `define_tokens` to create or update token sections:

- **colours** — palette, semantic colours, service colours, theme variants
- **typography** — font families, size scales, weights, line heights
- **spacing** — spacing scale, layout dimensions, component spacing
- **borders** — border radii, border styles, focus rings
- **shadows** — shadow values per theme, component assignments
- **breakpoints** — responsive breakpoints and behaviour rules

### Defining components, patterns, and voice

- `define_component` — define a UI component with variants, sizes, and usage notes
- `define_pattern` — define a layout or interaction pattern with structure and examples
- `define_voice` — define voice and tone rules for copy (errors, labels, docs, emails)

### Managing brand assets

- `upload_asset` — upload an image (PNG, SVG, JPEG, WebP, GIF, ICO) with usage rules and tags.
  Max 5MB, base64-encoded for MCP.
- `get_asset` — retrieve asset metadata and download URL by name
- `list_assets` — list all assets, optionally filtered by tags

### When to use the styleguide

- **Before building UI** — call `get_styleguide` or check the `styleguide` field from
  `bootstrap` to understand the project's visual language
- **After establishing design decisions** — store them with `define_tokens`, `define_component`,
  `define_pattern`, or `define_voice` so they persist across sessions
- **When uploading brand assets** — use `upload_asset` with clear `usage_rules` and
  `usage_context` so other agents know where and how to use each asset

---

## Tasks Service

Pick up assigned work, track progress, and coordinate with team members.

### Checking for tasks

At session start, `bootstrap` returns your assigned tasks under `assigned_tasks`, grouped by
status. You can also call `get_my_tasks` at any time to see your current work.

### Working through tasks

1. `get_my_tasks` — see your open and in-progress tasks
2. `get_task` — load full context including notes from team members
3. Do the work
4. `add_task_note` — record what you did
5. `update_task_status` — move the task forward (e.g. `open` → `review`)

### Bulk operations

When working on multiple tasks, use the bulk tools to reduce API calls:

- `bulk_get_tasks` — fetch up to 50 tasks with notes in one call
- `bulk_add_notes` — add notes to multiple tasks at once
- `bulk_update_status` — move multiple tasks to a new status at once

All bulk operations use all-or-nothing validation — if any item fails, the entire batch
is rejected.

### Workflow differences by plan

- **Solo plan** — fixed workflow: `open → review → done`. Tasks can only be assigned to agents.
- **Team plans** — custom workflows with up to 10 statuses. Tasks can be assigned to agents
  or team members. Team members and the project owner appear in the assignee dropdown.

---

## Quick Reference

| Action | Tool |
|--------|------|
| Start a session | `bootstrap` |
| Save something you learned | `store_context` |
| Record a deployment or change | `log_event` |
| Follow a procedure | `start_run` → `get_current_step` → `advance_step` |
| Log a user-facing change | `create_changelog_entry` |
| Submit feedback | `submit_feedback` |
| Check for in-progress work | `list_runs` with `status=running,paused` |
| Load the design system | `get_styleguide` |
| Define design tokens | `define_tokens` |
| Define a component | `define_component` |
| Upload a brand asset | `upload_asset` |
| Search the styleguide | `search_styleguide` |
| Check your assigned tasks | `get_my_tasks` |
| Get task details with notes | `get_task` |
| Add a note to a task | `add_task_note` |
| Move a task to a new status | `update_task_status` |
| Bulk fetch tasks | `bulk_get_tasks` |
| Bulk add notes | `bulk_add_notes` |
| Bulk update statuses | `bulk_update_status` |

Full API documentation: https://docs.minolith.io

What Happens Next

Once Claude Code has the MCP server connected and your CLAUDE.md in place:

  1. First session — Claude calls bootstrap, gets an empty project. As it works, it stores context entries (rules, patterns, decisions, warnings) about your codebase.

  2. Second session — Claude calls bootstrap again, this time loading everything it learned last time. It picks up exactly where it left off with full project knowledge.

  3. Over time — your project's knowledge base grows. New rules, patterns, and decisions are added. Stale entries are updated or removed. Events form a timeline of what happened and when.

The more your agent uses Minolith, the less context it loses between sessions and the fewer mistakes it repeats.

Troubleshooting

"MCP server not found" or tools not appearing

  • Check that .mcp.json is in your project root (or your home directory for global config)
  • Verify the API key is correct — test with curl -H "Authorization: Bearer YOUR_API_KEY" https://api.minolith.io/v1/context/entries
  • Restart Claude Code after modifying .mcp.json

"Authentication failed" errors

  • API keys start with mlth_ — make sure you're using a project API key, not your account password
  • Check the key hasn't been revoked in Dashboard → Settings → API Keys

Bootstrap returns no agent

  • This is normal for new projects. The fallback workflow in CLAUDE.md handles this case.
  • Create an agent definition with create_agent to get a full bootstrap experience.

Rate limiting (1 req/sec)

  • This applies to unverified email accounts. Verify your email address in Dashboard → Settings to remove the limit.

Last updated: 6 Apr 2026