# MCP Progress Notification System in Instagit: Real-Time Streaming Updates Explained

> Discover Instagit's MCP progress notification system for real-time streaming updates during AI analysis. Learn how progress tokens track concurrent requests efficiently.

- Repository: [Instalabs AI/instagit](https://github.com/instalabsai/instagit)
- Tags: deep-dive
- Published: 2026-02-16

---

**Instagit implements an MCP progress notification system that streams real-time status updates to clients every 250 milliseconds during AI analysis, using unique progress tokens to track concurrent requests.**

Instagit operates as an **MCP (Model-Context-Protocol) server**, enabling AI assistants to query Git repositories through standardized tool calls. When clients invoke the `ask_repo` tool, Instagit leverages its **MCP progress notification system** to deliver live feedback during streaming responses, allowing clients to monitor token usage and processing status in real time.

## How the MCP Progress Notification System Works

The system follows a structured protocol to maintain stateful communication between the Instagit server and MCP-compatible clients.

### Progress Token Generation

Every tool invocation receives a unique identifier to distinguish concurrent operations. In [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts), Instagit either reuses a client-provided token or generates a fresh one using a timestamp-based scheme.

```typescript
// src/index.ts – generate or reuse progress token
const progressToken = extra._meta?.progressToken ?? `ask_repo_${Date.now()}`;

```

This token serves as the correlation ID for all subsequent notifications related to that specific request.

### Sending Progress Notifications

Instagit transmits updates through the MCP channel using the standardized `notifications/progress` method. The `sendProgress` helper function in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) constructs payloads containing the token, current output token count, and human-readable status messages.

```typescript
// src/index.ts – emit progress notification
const sendProgress = async (message: string) => {
  try {
    await extra.sendNotification({
      method: "notifications/progress" as const,
      params: {
        progressToken,
        progress: tracker.outputTokens,
        message,
      },
    });
  } catch {
    // client may not support progress – ignore errors
  }
};

```

The system gracefully handles clients that do not implement progress support by catching and ignoring transmission errors.

### The Streaming Heartbeat

During active streaming operations in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts), a heartbeat mechanism triggers every **250 milliseconds** to provide continuous feedback. This interval ensures clients receive frequent updates without overwhelming the communication channel.

```typescript
// src/api.ts – heartbeat driving streaming updates
if (progressCallback) {
  heartbeatInterval = setInterval(async () => {
    if (!tracker.done) {
      try {
        await progressCallback(formatMessage(tracker));
      } catch {}
    }
  }, 250);
}

```

The heartbeat continues until the `ProgressTracker` marks the operation as complete, ensuring clients always know the processing status.

## Key Components of the Progress System

Two specialized modules handle the state management and presentation of progress data.

### ProgressTracker State Management

The `ProgressTracker` class maintains comprehensive metrics about the ongoing operation, including:

- **Timing data**: Start time and elapsed duration
- **Token counts**: Input and output token tallies
- **Status flags**: Completion state and error conditions

This state object updates continuously during streaming and serves as the single source of truth for progress calculations.

### Message Formatting

The `formatMessage` function in [`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts) transforms raw tracker data into concise, user-friendly status strings. It generates visual progress indicators using block characters and includes timing and token statistics.

```typescript
// src/kitt.ts – format progress for display
export function formatMessage(
  tracker: import("./types.js").ProgressTracker,
  status?: string,
  tokens?: { input?: number; output?: number }
): string {
  // Returns formatted string like: "█░░· 3s · 150 tokens · Connecting…"
}

```

This formatting ensures that progress notifications remain readable across different client implementations while providing technical details for debugging.

## Implementation Examples

### Server-Side Progress Emission

When implementing the `ask_repo` tool handler, integrate progress notifications using the established pattern from [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts):

```typescript
const progressToken = extra._meta?.progressToken ?? `ask_repo_${Date.now()}`;

const sendProgress = async (message: string) => {
  await extra.sendNotification({
    method: "notifications/progress" as const,
    params: {
      progressToken,
      progress: tracker.outputTokens,
      message,
    },
  });
};

```

### Client-Side Progress Handling

MCP clients receive progress notifications through event handlers. Implement a listener to update UI elements or log processing metrics:

```typescript
client.on("notifications/progress", ({ progressToken, progress, message }) => {
  // Update progress bar or status indicator
  console.log(`[${progressToken}] ${message} (tokens: ${progress})`);
});

```

The `progressToken` parameter allows clients to route updates to the correct UI component when handling multiple concurrent repository queries.

## Summary

Instagit’s **MCP progress notification system** enables real-time streaming updates through the following mechanisms:

- **Unique progress tokens** generated in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) to track individual tool invocations
- **Standardized MCP notifications** using the `notifications/progress` method with structured payloads
- **250-millisecond heartbeat intervals** in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts) ensuring continuous client feedback during streaming
- **ProgressTracker and formatMessage** utilities in [`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts) for state management and human-readable status formatting

This architecture allows MCP-compatible clients to monitor AI analysis progress, display token usage statistics, and provide responsive user interfaces during long-running repository queries.

## Frequently Asked Questions

### What is the MCP progress notification system in Instagit?

The **MCP progress notification system** is a real-time communication protocol implemented in Instagit that streams status updates to clients during AI-powered repository analysis. It uses the Model-Context-Protocol standard to send periodic notifications containing token counts, elapsed time, and processing status while the `ask_repo` tool generates responses.

### How often does Instagit send progress updates during streaming?

Instagit transmits progress updates every **250 milliseconds** through a heartbeat mechanism defined in [`src/api.ts`](https://github.com/instalabsAI/instagit/blob/main/src/api.ts). This interval balances real-time feedback with network efficiency, ensuring clients receive frequent status updates without overwhelming the MCP communication channel during long-running AI analysis operations.

### What information is included in an Instagit progress notification?

Each progress notification contains three key fields: the **progressToken** (unique request identifier), **progress** (current output token count from the ProgressTracker), and **message** (human-readable status string formatted by `formatMessage` in [`src/kitt.ts`](https://github.com/instalabsAI/instagit/blob/main/src/kitt.ts)). This payload allows clients to display visual progress bars, token usage statistics, and status messages simultaneously.

### Can Instagit’s progress notifications work with any MCP client?

Instagit’s progress notifications follow the **standard MCP protocol** using the `notifications/progress` method, making them compatible with any MCP-compliant client. However, the system gracefully handles unsupported clients by catching transmission errors in [`src/index.ts`](https://github.com/instalabsAI/instagit/blob/main/src/index.ts) and continuing operation without progress feedback, ensuring robust interoperability across different MCP implementations.