How Upgrade Hints and Tier Information Are Exposed in Instagit's API Responses

Instagit exposes upgrade hints and tier information through the AnalysisResult interface, populated from SSE stream events and rendered in the MCP server's CLI footer.

The instalabsAI/instagit repository implements a Model Context Protocol (MCP) server that streams repository analysis from a remote API. Understanding how upgrade hints and tier information are exposed in Instagit's API responses is essential for developers integrating usage limits and billing notifications into their own MCP tools.

Type Definitions for Tier and Usage Metadata

The foundation of this exposure lies in src/types.ts, where the AnalysisResult interface defines the contract between the API client and the MCP server. This interface includes three critical fields for usage tracking:

• tier: A string indicating the user's subscription level (e.g., "free", "pro")
• tokensRemaining: Numeric count of available credits left in the current billing period
• upgradeHint: An optional string containing contextual upgrade suggestions when limits are approached

Extracting Usage Data from SSE Streams

The src/api.ts file handles the actual communication with the Instagit API endpoint /v1/responses. Rather than using standard JSON request-response patterns, this implementation utilizes Server-Sent Events (SSE) to stream analysis results.

When the client receives an event of type response.completed, it extracts a usage object from the payload. The mapping logic translates the API's snake_case fields to the client's camelCase properties:

• usage.tier → result.tier
• usage.tokens_remaining → result.tokensRemaining
• usage.upgrade_hint → result.upgradeHint

This transformation occurs within the analyzeRepoStreaming function, which returns a fully populated AnalysisResult object to the caller.

Rendering Tier Information in the MCP Server

Once the client library returns the AnalysisResult, the MCP server in src/index.ts formats this data for display in the command-line interface. The server constructs a footer section that appears after the main analysis text.

The formatting logic conditionally appends usage information:

1. Token counts are displayed first (input, output, and total tokens)
2. Tier information follows, showing the current subscription level
3. Remaining credits appear when tokensRemaining is greater than zero
4. Upgrade hints are appended as a separate paragraph when present, providing context such as "Upgrade to Pro for unlimited repository size"

Complete Data Flow from API to User

Understanding the full path of upgrade hints and tier information helps developers debug usage-related issues:

1. Remote API (https://instagit--instagit-api-api.modal.run/v1/responses) sends SSE events containing the usage object upon completion
2. API Client (src/api.ts) parses the response.completed event and maps usage fields to the AnalysisResult interface
3. MCP Server (src/index.ts) receives the result and formats a user-visible footer with tier, credits remaining, and upgrade suggestions
4. End User sees the formatted output in their CLI or IDE integration, including contextual hints about subscription limits

Practical Implementation Examples

Consuming Tier Data in Your Integration

import { analyzeRepoStreaming } from "./api";

async function checkUsage() {
  const result = await analyzeRepoStreaming({
    repo: "github.com/owner/repo",
    prompt: "Analyze codebase architecture",
  });

  console.log(`Current tier: ${result.tier}`);
  console.log(`Credits remaining: ${result.tokensRemaining}`);
  
  if (result.upgradeHint) {
    console.warn(`Limit warning: ${result.upgradeHint}`);
  }
}

Formatting Usage Data for Display

// Simplified excerpt from src/index.ts
function formatResponse(result: AnalysisResult): string {
  let output = result.text;
  const footerParts: string[] = [];

  if (result.tier) {
    footerParts.push(`Tier: ${result.tier}`);
  }
  
  if (result.tokensRemaining > 0) {
    footerParts.push(`Credits: ${result.tokensRemaining}`);
  }

  if (footerParts.length) {
    output += "\n\n---\n" + footerParts.join(" | ");
  }

  if (result.upgradeHint) {
    output += `\n\n${result.upgradeHint}`;
  }

  return output;
}

Summary

• Type definitions in src/types.ts establish the AnalysisResult interface with tier, tokensRemaining, and upgradeHint fields
• API client in src/api.ts extracts usage metadata from SSE response.completed events and maps snake_case API fields to camelCase result properties
• MCP server in src/index.ts formats tier information and upgrade hints into a user-visible footer appended to analysis results
• Data flow follows a clear path: Remote API → SSE stream → Client mapping → Server formatting → CLI display

Frequently Asked Questions

What fields contain tier and upgrade information in the API response?

The Instagit API returns tier and upgrade metadata within the usage object of a response.completed SSE event. This object contains tier (string), tokens_remaining (number), and upgrade_hint (optional string), which the client library maps to tier, tokensRemaining, and upgradeHint in the AnalysisResult interface.

How does the MCP server display upgrade hints to users?

The MCP server in src/index.ts appends upgrade hints to the analysis output after a separator line. When result.upgradeHint is present, the server adds two newlines followed by the hint text directly to the response string, making it appear as a distinct message below the usage footer in the CLI interface.

Can I access tier information programmatically without parsing the CLI output?

Yes, the analyzeRepoStreaming function in src/api.ts returns a complete AnalysisResult object that includes the tier, tokensRemaining, and upgradeHint fields as typed properties. You can import this function directly and access these values programmatically without relying on the MCP server's string formatting.

What happens when the API does not include an upgrade hint?

When the API response omits the upgrade_hint field, the upgradeHint property in the AnalysisResult object will be undefined. The MCP server checks for the presence of this field before appending it to the output, so no upgrade message appears in the CLI when the hint is not provided by the API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}