Instagit Anonymous Token Limitations and Upgrade Guide

Instagit’s anonymous token system restricts users to three tokens per IP address, shared free-tier credits, and a 2 GB repository limit, but upgrading to a paid plan via the INSTAGIT_API_KEY environment variable removes these restrictions entirely.

The instalabsAI/instagit repository provides a Model Context Protocol (MCP) server for AI-powered Git repository analysis. While the tool offers an anonymous token mode for quick experimentation, production use requires understanding its hard limits and the upgrade path to authenticated API access.

How Instagit’s Anonymous Token System Works

Instagit operates in two distinct authentication modes, controlled primarily by the presence of an API key.

Anonymous Token Registration

When no API key is present, the client automatically requests a temporary token via the registerAnonymousToken function in src/token.ts (lines 60-78). This function sends a POST /v1/auth/anonymous request to the Instagit API, creating a token bound to the requesting IP address.

API Key Authentication

Paid users bypass the anonymous flow entirely. The getOrCreateToken function in src/token.ts (lines 45-55) checks for the INSTAGIT_API_KEY environment variable first. If present, it returns the key directly, skipping registration and removing all anonymous-tier limitations.

Instagit Anonymous Token Limitations

The anonymous system imposes three specific hard caps designed to prevent abuse of the free tier.

3-Token-per-IP Cap

The server enforces a strict limit of three anonymous tokens per public IP address. When a fourth registration attempt occurs from the same IP, the API refuses the request. This error handling is implemented in src/index.ts (lines 99-107), where the server returns a specific error message directing users to upgrade.

Shared Free-Tier Credit Pool

Anonymous tokens draw from a communal pool of free credits. When this pool is exhausted, the API returns HTTP 429 Rate-Limited. The client handles this in src/index.ts (lines 48-66) by displaying an upgrade hint pointing to the pricing page. This is not a per-user limit but a global resource shared across all anonymous users.

2 GB Repository Size Ceiling

The free tier rejects repositories larger than 2 GB, returning HTTP 413 Payload Too Large. This limit prevents excessive bandwidth consumption on the shared infrastructure. Paid plans remove this ceiling entirely, with the Max plan specifically advertising unlimited repository sizes.

How to Upgrade from Anonymous Tokens

Upgrading requires obtaining an API key from the Instagit dashboard and configuring your environment.

Set the INSTAGIT_API_KEY environment variable to your paid key:

export INSTAGIT_API_KEY="sk_live_..."

The Pro plan ($20/month) provides 10× more credits than the free tier, while the Max plan removes repository size limits entirely. Once the key is set, getOrCreateToken in src/token.ts automatically uses it, bypassing all anonymous limitations.

Code Examples

Using an Explicit API Key in Production

// Set the environment variable before importing Instagit
process.env.INSTAGIT_API_KEY = "sk_live_…"; // replace with your real key

import { getOrCreateToken } from "./token.js";

const token = getOrCreateToken(); // returns the API key directly
console.log("Using paid token:", token);

This approach works because getOrCreateToken checks process.env.INSTAGIT_API_KEY first (lines 45-48 of src/token.ts), skipping the anonymous registration flow entirely.

Handling the 3-Token-per-IP Error

import { registerAnonymousToken } from "./token.js";

async function obtainToken(apiUrl: string) {
  const token = await registerAnonymousToken(apiUrl);
  if (!token) {
    console.error(
      "Reached the 3-anonymous-token limit. " +
      "Create an account and set INSTAGIT_API_KEY to continue."
    );
    return null;
  }
  return token;
}

This mirrors the error handling logic found in src/index.ts (lines 99-107), providing a clear path to resolution when the IP limit is reached.

Detecting Rate Limit Responses

import { analyzeRepoStreaming } from "./api.js";

try {
  await analyzeRepoStreaming({ repo, prompt, token });
} catch (err: any) {
  if (err.status === 429) {
    console.log(
      "Free credits exhausted. Upgrade to Pro for more credits: " +
      "https://app.instagit.com/pricing"
    );
  }
}

The server surfaces rate limits via HTTP 429, as handled in src/index.ts (lines 48-66), often including an upgradeHint field in the response.

Summary

• Anonymous tokens are auto-generated via registerAnonymousToken in src/token.ts but impose strict limits: 3 tokens per IP, shared credit pools, and 2 GB repo caps.
• Rate limiting (HTTP 429) occurs when the global free credit pool is exhausted, handled in src/index.ts.
• Upgrading requires setting INSTAGIT_API_KEY, which causes getOrCreateToken to bypass anonymous registration entirely, removing all limits.
• Pro and Max plans offer 10× credits and unlimited repository sizes, respectively.

Frequently Asked Questions

What happens when I hit the 3-token-per-IP limit in Instagit?

When you attempt to register a fourth anonymous token from the same public IP address, the API refuses the request and the client displays an error message directing you to create an account. As implemented in src/index.ts (lines 99-107), this hard cap prevents abuse of the free tier and can only be bypassed by upgrading to a paid API key.

How do I know if Instagit has run out of free credits?

The API returns an HTTP 429 Rate-Limited status when the shared free-tier credit pool is exhausted. The client catches this in src/index.ts (lines 48-66) and prints a message suggesting an upgrade to the Pro plan. Unlike per-user limits, this indicates global pool depletion that affects all anonymous users simultaneously.

Can I use Instagit with large repositories on the free tier?

No. The anonymous token system enforces a 2 GB repository size limit, returning HTTP 413 Payload Too Large for bigger repositories. This ceiling is removed only on paid plans, with the Max plan specifically offering unlimited repository sizes. To analyze larger repos, you must set the INSTAGIT_API_KEY environment variable with a paid key.

Where should I store my Instagit API key for production use?

Set the INSTAGIT_API_KEY environment variable before starting the Instagit server. The getOrCreateToken function in src/token.ts (lines 45-55) checks this variable first and returns it directly, completely bypassing the anonymous token flow. While you can manually store keys in ~/.instagit/token.json, environment variables are the recommended approach for production deployments.

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