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.

Copy your API key

Your API key is shown once during onboarding. Copy it and keep it safe. You can create additional keys anytime from Settings.

Connect your tool

Use a one-click deeplink or add the MCP server manually. Foremen works with any tool that supports MCP.

Cursor

One-click deeplink installs Foremen as an MCP server

VS Code

Deeplink or add to settings.json manually

Claude Code

One CLI command to add the MCP server

Windsurf

One-click deeplink via MCP registry

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

30 tools across 12 categories. All tools accept JSON arguments via the MCP protocol.

Project Management

(2)

list_projects

List all projects in your Foremen account.

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

(3)

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_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

(2)

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)

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

(5)

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

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]

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:

{
  "mcpServers": {
    "foremen": {
      "url": "https://your-foremen-instance.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Connect to Claude Code

Run a single CLI command to add Foremen as an MCP server:

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

Replace the URL and API key with your actual values from the Foremen dashboard.

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:

{
  "mcp": {
    "servers": {
      "foremen": {
        "type": "http",
        "url": "https://your-foremen-instance.com/api/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

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

Add your API key as a Bearer token in the authentication section

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

MCP Endpoint: https://your-foremen-instance.com/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.

API key authentication

Every MCP request requires a valid Bearer token. Keys are hashed before storage. You can revoke keys instantly from the dashboard.

API Reference

Endpoint

POST https://your-foremen-instance.com/api/mcp

Authentication

All requests must include a Bearer token in the Authorization header. Get your API key from the Foremen 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