Documentation

Everything you need to connect your AI coding tools to Foremen and give your agents persistent project memory.

Quickstart

Get up and running in under two minutes.

Sign up and create a project

Create a free account, then create a project. A project maps to one codebase. You will get an API key automatically.

Connect your tool — no API key needed

Foremen supports MCP OAuth: point your tool at the endpoint and it opens a browser window to sign in with your Foremen account. One connection covers every project on your account. For Claude Code that's a single command:

claude mcp add --transport http foremen https://foremen.app/api/mcp

Cursor & VS Code

One-click deeplink, then sign in when prompted

claude.ai & ChatGPT

Add the endpoint URL as a connector and sign in

Tools that can't sign in can use an API key instead — see the per-tool sections below.

Verify it works

Ask your agent to call get_session_brief for your project. Your project page in the dashboard updates the moment Foremen receives its first call.

Concepts

The core abstractions in Foremen.

Projects

A project maps to one codebase. It holds all the context your agents need: architecture, lessons, tasks, guardrails, and session history. Agents can reference projects by UUID or slug.

Session Briefs

A single-call briefing that assembles everything an agent needs at session start: current task, recent session notes, lessons learned, active decisions, architecture state, and auto-resolved references.

Lessons

Patterns learned from debugging, development, or discovery. Each lesson captures what to watch for (pattern), what goes wrong if ignored (impact), and how to fix it. Surfaced automatically in future briefs.

Decisions

Architectural and technical decisions with context and rationale. Decisions can be permanent or temporary with expiration dates. Active decisions appear in session briefs so agents respect them.

Guardrails

Protection rules that prevent agents from touching sensitive files, directories, or components. Guardrails have severity levels: info, warning, critical, and blocked. The consult tool checks them automatically.

Architecture

A living map of your system's components. Each component has a name, type (frontend, backend, database, etc.), status, and description. Agents update this as they build features.

Session Notes

Append-only, timestamped notes that persist across chat sessions. Agents use these to leave breadcrumbs: progress updates, decisions made, blockers hit, or context the next session needs.

Check-in / Check-out

Lightweight agent coordination. Check-in registers what an agent is working on and which files it will touch. Check-out records what was accomplished. Used for conflict detection when multiple agents work on the same project.

MCP Tools Reference

65 tools across 16 categories. All tools accept JSON arguments via the MCP protocol.

Project Management

(3)

list_projects

List all projects in your Foremen account.

create_project

Create a new project. Use when starting on a codebase that has no matching Foremen project yet. Returns the new id and slug.

Required

name(string)Human-readable project name

Optional (5)

description(string)Short description of what the project is

current_focus(string)What is being worked on now — tops every session brief

repo_url(string)URL of the code repository

repo_provider(string)Where the repository lives [github, gitlab, local]

tech_stack(string[])Technologies used, seeded on creation

get_current_focus

Get the current focus/task for a project.

Required

project_id(string)The UUID or slug of the project

Session

(3)

get_session_brief

Get a comprehensive pre-session briefing. Call this at the START of every new chat session. Returns project overview, current focus, session notes, current/next task with full prompt, auto-resolved references, lessons, decisions, architecture, and recent activity.

Required

project_id(string)The UUID or slug of the project

add_session_note

Write a note that persists across chat sessions. Use this to leave breadcrumbs for the next agent/chat.

Required

project_id(string)The UUID or slug of the project

content(string)The note content. Be specific — include what was done, what's left, any gotchas.

Optional (1)

metadata(object)Optional structured metadata (e.g. { task_id, files_touched })

get_session_notes

Read session notes for a project. Returns the most recent notes left by previous agents/chats.

Required

project_id(string)The UUID or slug of the project

Optional (1)

limit(number)Max number of notes to return (default 20)

Tasks

(5)

get_tasks

Get the to-do list for a project. Each task has a prompt with instructions for what to do.

Required

project_id(string)The UUID or slug of the project

Optional (1)

status(string)Filter by status [pending, in_progress, completed, skipped]

get_next_task

Get the next pending task to work on. Returns the highest priority pending task with its prompt.

Required

project_id(string)The UUID or slug of the project

start_task

Mark a task as in_progress when you begin working on it.

Required

task_id(string)The UUID of the task

complete_task

Mark a task as completed. If the task has requires_new_chat=true, the agent will tell the user to start a new chat.

Required

task_id(string)The UUID of the task

Optional (1)

summary(string)Brief summary of what was done

add_task

Add a new task to the project's to-do list.

Required

project_id(string)The UUID or slug of the project

title(string)Short title for the task

prompt(string)The full prompt/instructions for the AI to execute this task

Optional (3)

description(string)Human-readable description

priority(number)Priority (higher = more important, default 0)

requires_new_chat(boolean)Whether to suggest starting a new chat after this task

Knowledge

(2)

learn_lesson

Record a lesson learned from debugging, development, or discovery. Stores the pattern to watch for, the impact, and the fix. Lessons are surfaced in future session briefs.

Required

project_id(string)The UUID or slug of the project

title(string)Short name for the lesson (e.g. 'OAuth tokens expire after 1hr')

pattern(string)What to watch for — describe the pattern conceptually

Optional (7)

impact(string)What goes wrong if this is ignored

fix(string)How to solve or avoid the problem

origin_file(string)File path where the fix was made

origin_before(string)Code snippet before the fix

origin_after(string)Code snippet after the fix

origin_description(string)Description of the code change

tags(string[])Searchable tags (e.g. ['auth', 'github'])

get_lessons

Get lessons learned for a project. Returns patterns, impacts, fixes, and code origins. Use this when debugging or before making changes.

Required

project_id(string)The UUID or slug of the project

Optional (2)

tag(string)Filter lessons by tag (e.g. 'auth', 'database')

query(string)Search lessons by keyword in title, pattern, or fix

Architecture

(1)

update_architecture

Add or update a component in the project's architecture. If a component with the same name exists, it will be updated.

Required

project_id(string)The UUID or slug of the project

name(string)Name of the component (e.g. 'Cart API', 'Auth Service')

Optional (3)

type(string)Type of component [frontend, backend, database, external, service]

description(string)What this component does, key files, and how it connects

status(string)Current status [planned, in-progress, done]

Agent Coordination

(4)

check_in

Call at the start of a work session. Registers what you're about to work on so other tools can see active work and avoid conflicts.

Required

project_id(string)The UUID or slug of the project

work_description(string)One sentence: what you're about to do

Optional (2)

files_involved(string[])File paths you expect to touch

tool(string)Which tool is working (e.g. 'claude-code', 'cursor')

check_out

Call when done working. Records what was accomplished briefly.

Required

project_id(string)The UUID or slug of the project

summary(string)One sentence: what you did

Optional (3)

files_created(string[])Files created during this session

files_modified(string[])Files modified during this session

task_id(string)If working on a specific task, mark it done

check_directives

Check for directives — standing instructions the project owner wrote that should reach the working agent at specific moments. For tools without the automatic hook.

Required

project_id(string)The UUID or slug of the project

event(string)The moment being checked

Optional (3)

session_id(string)Stable session id, so the same directive is not delivered twice

file_path(string)For post_tool_use: the file just edited

prompt(string)For user_prompt: the user's request text

check_conflicts

Before modifying files, check if another agent recently touched them. Returns recent activity within the last 2 hours.

Required

project_id(string)The UUID or slug of the project

files(string[])File paths you plan to modify

Guardrails

(3)

add_guardrail

Add a guardrail to protect a file, directory, or component from accidental modification.

Required

project_id(string)The UUID or slug of the project

target_type(string)What type of thing is being protected

target_path(string)The path or name to protect

message(string)The warning message to show

Optional (2)

severity(string)How severe the guardrail is [info, warning, critical, blocked]

reason(string)Detailed explanation

get_guardrails

Get all active guardrails for a project. Call this before making changes.

Required

project_id(string)The UUID or slug of the project

Optional (1)

check_path(string)Check if a specific path matches any guardrails

remove_guardrail

Remove a guardrail by ID.

Required

guardrail_id(string)The UUID of the guardrail to remove

References

(3)

list_references

List all references (prompts, style guides, AI instructions) for a project.

Required

project_id(string)The UUID or slug of the project

Optional (2)

type(string)Filter by type [prompt, style_guide, ai_instructions]

tag(string)Search by reference tag (partial match)

add_reference

Create or update a reference — a prompt, design system, AI instruction set, or documentation — that other agents fetch by tag. The write half of get_reference.

Required

project_id(string)The UUID or slug of the project

type(string)What kind of reference this is

title(string)Human-readable name

reference_tag(string)The address other agents fetch this by. Matched partially, so make it distinctive

content(string)The reference body, plain text or markdown

Optional (2)

description(string)One line describing what this is

attach_to(string)Tag or UUID of a parent reference

get_reference

Get a specific reference by ID or tag. Returns full content including uploaded files and all attached references auto-resolved.

Required

project_id(string)The UUID or slug of the project

Optional (2)

reference_id(string)The UUID of the reference

reference_tag(string)The reference tag to search for

Documents

(12)

add_document

Write a document into a reference so agents can search it and pull single sections out. The write half of search_documents and get_document_section.

Required

project_id(string)The UUID or slug of the project

name(string)What this document is called

content(string)The document as markdown. Split into sections on # and ## headings

Optional (3)

reference_tag(string)The reference this belongs under. Partial match supported

reference_id(string)The parent reference's UUID, if known exactly

summary(string)One paragraph on what this document covers

search_documents

Search across all processed documents in a project by keyword or query. Returns matching sections with titles and tags.

Required

project_id(string)The UUID or slug of the project

query(string)Search query — keywords or natural language

Optional (1)

reference_id(string)Scope search to documents attached to a specific reference

get_document_section

Fetch a specific section from a processed document by title or index.

Required

document_id(string)The UUID of the document

Optional (2)

section_title(string)Title of the section to fetch (partial match)

section_index(number)Zero-based index of the section

find_relevant_docs

Given a task description or question, searches all project references and documents to find the most relevant ones.

Required

project_id(string)The UUID or slug of the project

query(string)Description of what you're working on

expand_prompt

Expands a prompt reference by inlining all attached documents, linked references, and optionally project context. Returns a fully-resolved prompt.

Required

reference_id(string)The UUID of the reference (prompt) to expand

Optional (1)

include_project_context(boolean)Include full project context in the expanded prompt (default: false)

sync_project

Re-scan a GitHub-connected project to sync tech stack, components, and references from the repository.

Required

project_id(string)The UUID or slug of the project

rename_project

Rename a project. Changes only the display name by default — the slug stays put, because wired repos resolve against it.

Required

project_id(string)The UUID or slug of the project

name(string)The new display name

Optional (2)

new_slug(string)Explicit new slug. Breaks repos wired to the old one until re-initialised.

update_slug(boolean)Derive a new slug from the new name (default: false)

create_group

Group related projects so they can see each other's decisions and lessons. A project can belong to several groups.

Required

name(string)Group name, e.g. "Shared Supabase Catalog"

Optional (2)

description(string)What ties these projects together

project_ids(array)UUIDs or slugs to add immediately

list_groups

List your project groups and which projects belong to each.

add_project_to_group

Add a project to an existing group. Safe to call repeatedly.

Required

group(string)The UUID, slug, or exact name of the group

project_id(string)The UUID or slug of the project

remove_project_from_group

Remove a project from a group. The project and its data are untouched.

Required

group(string)The UUID, slug, or exact name of the group

project_id(string)The UUID or slug of the project

get_group_context

Full picture from sibling projects in the same group — decisions, lessons, open and completed tasks, recent activity, session notes. Call before touching anything shared.

Required

project_id(string)The project you are working on; its groups are found automatically

Optional (2)

limit_per_project(number)Max rows of each kind per sibling (default: 10, max 25)

include(array)Narrow to any of: decisions, lessons, tasks, activity, notes (default: all)

Consultation

(1)

consult_foremen

Ask Foremen for a second opinion on a decision or action. Checks guardrails, lessons, architecture, and project history to give an informed recommendation.

Required

project_id(string)The UUID or slug of the project

question(string)The question or decision you need help with

Optional (3)

context(string)Additional context about what you're trying to accomplish

files_involved(string[])List of file paths that might be affected

proposed_action(string)What you're planning to do

Conversations

(2)

import_chat

Import and process a raw chat export from Claude, ChatGPT, Cursor, or any AI tool. Parses the conversation and extracts decisions, Q&A, and key moments with anchor links.

Required

project_id(string)The UUID or slug of the project

chat_content(string)The raw chat transcript

Optional (5)

source(string)Which AI tool the chat came from [claude, chatgpt, cursor, copilot, other]

title(string)Title for this conversation

commit_hash(string)Git commit hash to link to

files_involved(string[])Files that were discussed or modified

session_id(string)Link to an agent session

search_conversations

Search past imported conversations for decisions, Q&A, problems, solutions, and insights.

Required

project_id(string)The UUID or slug of the project

query(string)What to search for

Optional (3)

chunk_type(string)Filter to specific chunk types [decision, question, problem, solution, insight, warning, todo, reference]

file_path(string)Filter to conversations mentioning a specific file

limit(number)Max results to return (default 15)

Activity

(1)

report_activity

Report what you just did in a coding session — files created, modified, summary of work.

Required

project_id(string)The UUID or slug of the project

summary(string)Brief summary of what was done

Optional (5)

type(string)Type of activity [implementation, fix, refactor, docs, other]

component(string)Name of the component worked on

files_created(string[])List of files created

files_modified(string[])List of files modified

status_change(string)Status change for the component [started, in_progress, completed, blocked]

Decisions

(3)

add_decision

Record a decision made during development. A one-liner is fine. Decisions surface in future session briefs so other agents know what was already settled.

Required

project_id(string)The UUID or slug of the project

title(string)Short name, e.g. 'REST not GraphQL'

decision(string)The decision itself — one sentence is ideal

Optional (3)

context(string)Why it was made, what alternatives were considered

scope(string)Permanent, or temporary and auto-expiring [permanent, temporary]

expires_at(string)ISO date a temporary decision expires

list_decisions

List active decisions. Expired temporary ones are filtered out automatically.

Required

project_id(string)The UUID or slug of the project

Optional (1)

include_expired(boolean)Include expired temporary decisions

deprecate_decision

Mark a decision as superseded. It stops appearing in session briefs.

Required

decision_id(string)The UUID of the decision

Optional (1)

reason(string)What superseded it

Artifacts

(3)

save_artifact

Keep a working file past the end of the session that produced it — a rollback snapshot, generated SQL, a test harness. Text only, capped at 256KB.

Required

project_id(string)The UUID or slug of the project

name(string)File name as it was on disk

content(string)The file's contents, verbatim

Optional (3)

kind(string)What this is for [rollback, script, output, data, log, other]

summary(string)One line on when someone would want it

session_id(string)Groups everything kept from one session

list_artifacts

List working files kept from earlier sessions — what was saved, when, how big, what it was for. Metadata only.

Required

project_id(string)The UUID or slug of the project

Optional (3)

kind(string)Only artifacts of this kind [rollback, script, output, data, log, other]

session_id(string)Only artifacts kept from this session

limit(number)Maximum to return (default 30)

get_artifact

Read one artifact back in full, by name or id. Find candidates with list_artifacts first — this returns the whole file.

Required

project_id(string)The UUID or slug of the project

Optional (3)

name(string)The artifact's file name

artifact_id(string)The artifact's UUID, when known exactly

session_id(string)Disambiguates the same name across sessions

Slot

(11)

slot_connect

Connect this session to a shared slot space using its 6-character code. One-time setup.

Required

code(string)The 6-character space code shown in the Slot web app

slot_status

Report which slot space is connected, how many entries it holds, and what the current context is.

slot_context

Get the current slot context — the most recent deliberate capture. Call this when the user says 'check the slot' or refers to output they just sent.

Optional (2)

offset(integer)Start character for long content

limit(integer)How many characters to return

slot_get

Read one entry. Accepts a slot://SPACE/CLIP reference copied from the web app — read it immediately when one appears in the user's message — or a bare 4-character code.

Required

code(string)A slot://SPACE/CLIP reference, or a 4-character entry code

Optional (2)

offset(integer)Start character for long content

limit(integer)How many characters to return

slot_list

List recent entries with their 4-character codes and short previews.

Optional (4)

limit(integer)How many to return (default 20)

kind(string)Filter by kind [text, image]

since(string)ISO8601 — only entries created after this

space(string)Read a named space instead of the connected one

slot_latest

Get the most recent entry, optionally filtered to failed command captures. Answers 'what broke last?'

Optional (3)

kind(string)Filter by kind [text, image]

failed_only(boolean)Only captures whose exit code was non-zero

space(string)Read a named space instead of the connected one

slot_put

Write into a slot. With `space`, this is how you message the person on the other end of a handoff — it lands on their open page immediately.

Required

content(string)The text to write

Optional (4)

label(string)Short human label for the entry

kind(string)Entry kind [text, link]

context(boolean)Mark this as the space's current context

space(string)Write into a named space instead of the connected one

slot_wait

Wait for the other side to reply. Blocks up to 25 seconds and returns the moment something lands. Skips agent-written entries so you never answer yourself.

Optional (4)

space(string)The space to watch. Omit for the connected one

since(string)ISO8601 — pass back the value from a timed-out call to keep waiting

timeout_seconds(integer)How long to wait, 5 to 25 seconds

include_agent(boolean)Also return agent-written entries

slot_handoff

Open a scratch slot for someone else and return every way of sending output into it, ready to forward: a browser link, a pipe-to-curl command, a file upload, and a one-line connect command for their own agent.

Optional (3)

purpose(string)What is being collected, e.g. 'the build error'

recipient(string)Who the handoff is for

space(string)Reuse an existing space instead of opening a new one

slot_search

Full-text search across entries in the connected slot.

Required

query(string)What to search for

Optional (1)

limit(integer)How many results to return

slot_delete

Archive one entry by its 4-character code. Soft delete — the code returns to the pool.

Required

code(string)The 4-character entry code

Client Updates

(8)

create_client_update

Create (or update) a client update from a Markdown spec and optionally publish and email it. Renders as a designed page at /updates/<slug>. One commit, one update.

Required

title(string)Update title; also the email subject

Optional (8)

id(string)Update an existing update instead of creating one

subtitle(string)Short line under the title

client_name(string)Who the update is addressed to

recipient_email(string)Where to send it

theme(string)Which visual theme to render in

spec(string)Markdown body. A TUTORIAL line embeds a recorded walkthrough inline; 'TUTORIAL: tbd | name' holds an empty slot for one you have not recorded yet

publish(boolean)Publish the page as well as saving it

send(boolean)Email it once published

send_client_update

Email a published update.

Required

id(string)The update to send

Optional (1)

email(string)Override the stored recipient

create_onboarding_study

Create or update a client-facing onboarding deliverable, such as a naming study, shared at /onboarding/<client_slug>/discover. Each step is a self-contained presentation page.

Required

client_name(string)Client's full name, shown on the page

steps(object[])Ordered presentation steps. Put the primary recommendation first

Optional (4)

client_slug(string)URL slug for the share link. Derived from client_name if omitted

title(string)Deliverable title (default 'Naming Discovery')

prepared_on(string)Human-readable date shown in the header

themes(object[])Optional look-and-feel phase shown after the client picks a name

list_tutorial_slots

List the places a walkthrough is meant to go. Open slots are what is left to record — the client sees nothing where they sit.

Optional (2)

update(string)Limit to one update, by id or slug

include_filled(boolean)Also list slots that already hold a tutorial

fill_tutorial_slot

Drop a recorded tutorial into an open slot. The video appears where the slot was reserved — no re-authoring, no second link to send.

Required

tutorial(string)A /watch link, its token, or the tutorial id

Optional (3)

update(string)Which update, by id or slug

slot(string)Which slot, by handle or name. Omit when only one is open

caption(string)Optional line printed under the video

list_client_updates

List updates with their status, slug and published URL.

list_queued_updates

List updates waiting to be sent, so a week of work can go out as one note instead of five.

send_queued_updates

Send everything currently queued, together.

Connect to Cursor

Option 1: One-click install

During onboarding, Foremen generates a deeplink that installs the MCP server directly into Cursor. Click the button and Cursor will open with Foremen pre-configured.

Cursor Deeplink

cursor://anysphere.cursor-deeplink/mcp/install?name=foremen&config=...

Option 2: Manual configuration

Add Foremen to your .cursor/mcp.json file in your project root. With just the URL, Cursor opens a browser to sign in (recommended):

{
  "mcpServers": {
    "foremen": {
      "url": "https://foremen.app/api/mcp"
    }
  }
}

Or authenticate with an API key instead:

{
  "mcpServers": {
    "foremen": {
      "url": "https://foremen.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Connect to Claude Code

One command, no key — Claude Code opens a browser window to sign in with your Foremen account:

claude mcp add --transport http foremen https://foremen.app/api/mcp

Prefer an API key (for CI or headless machines)? Pass it as a header:

claude mcp add --transport http foremen \
  https://foremen.app/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Connect to VS Code

Option 1: One-click install

Use the VS Code deeplink from the Foremen onboarding flow. It opens VS Code and adds the MCP server to your configuration automatically.

VS Code Deeplink

vscode:mcp/install?...

Option 2: Manual configuration

Add to your VS Code settings.json. Without headers, VS Code runs the OAuth sign-in flow; add an Authorization header only if you want to use an API key instead:

{
  "mcp": {
    "servers": {
      "foremen": {
        "type": "http",
        "url": "https://foremen.app/api/mcp"
      }
    }
  }
}

Connect to ChatGPT

ChatGPT supports MCP servers via the Connectors feature.

Open ChatGPT and go to Settings

Navigate to Connectors and click Create

Enter the Foremen MCP endpoint URL — ChatGPT will prompt you to sign in with your Foremen account (OAuth)

Save the connector. Foremen tools will appear in your ChatGPT sessions.

MCP Endpoint: https://foremen.app/api/mcp

Security

Per-customer encryption

Every customer's data is encrypted with their own unique key. We cannot read your data. If you revoke access, your data becomes permanently unreadable.

Row-level security

Every database query is scoped to your user. No customer can access another customer's data, even through the API.

No code stored

Foremen stores project context — architecture, lessons, decisions — but never your source code. Your code stays in your repos.

Encrypted at rest

All data is encrypted at rest using industry-standard encryption. Data in transit is always TLS-encrypted.

OAuth & API key authentication

Every MCP request requires a valid Bearer token — an OAuth token from signing in, or an API key. Keys are verified against a SHA-256 hash; a copy encrypted with your per-customer key lets you view them in the dashboard, and you can revoke them instantly.

API Reference

Endpoint

POST https://foremen.app/api/mcp

Authentication

All requests must include a Bearer token in the Authorization header — either an OAuth access token (unauthenticated requests get a 401 with OAuth discovery metadata, so MCP clients handle sign-in automatically) or an API key from the dashboard.

Authorization: Bearer your_api_key_here

Protocol

Foremen uses the JSON-RPC 2.0 protocol over HTTP, as specified by the Model Context Protocol (MCP). The server supports Streamable HTTP transport.

Supported protocol versions: 2025-11-25, 2025-03-26, 2024-11-05

Example: Initialize

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    },
    "capabilities": {}
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": { "listChanged": false }
    },
    "serverInfo": {
      "name": "monolink",
      "version": "0.1.0"
    }
  }
}

Example: Call a tool

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_session_brief",
    "arguments": {
      "project_id": "my-project-slug"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Session Brief: my-project\n\n..."
      }
    ]
  }
}

Session management

The server returns a Mcp-Session-Id header after initialization. Include this header in subsequent requests. Sessions expire after 24 hours.

Error codes

Code	Meaning
-32700	Parse error — invalid JSON
-32601	Method not found
-32000	Unauthorized — invalid or missing API key
401	HTTP authentication required (triggers OAuth flow)
404	Invalid or expired session