Complete Troubleshooting Guide for Antigravity MCP Connection Errors

When working with Antigravity's MCP (Model Context Protocol) integration, connection errors can disrupt your workflow. This guide walks you through the most common issues and their solutions, from server startup failures to authentication problems.

How MCP Connection Works

MCP is the protocol that bridges Antigravity with external tools like GitHub, Figma, and custom servers. Antigravity manages multiple MCP servers simultaneously, allowing agents to call their functionality on demand.

The connection flow:

MCP server starts (Node.js process)
Antigravity initiates a connection attempt
JSON-RPC messages are exchanged for initialization
Agent tools become available

Failures at any stage trigger connection errors.

When MCP Server Fails to Start

1. Node.js Version Mismatch

Most MCP servers require Node.js 16 or higher. If you see "Server Failed to Start" in Antigravity Builder, check your Node.js version first.

# Check Node.js version
node --version
 
# Recommended: v18 or higher
# If v16, consider upgrading via official Node.js site

If outdated:

Download the latest Node.js from nodejs.org
Completely quit Antigravity (Cmd+Q)
Restart Antigravity
Reconnect the MCP server

2. JSON Configuration Format Errors

MCP servers are defined in ~/.antigravity/mcp_servers.json or mcp.json. Even a single syntax error stops the server cold.

// ✅ Correct format
{
  "servers": {
    "github": {
      "command": "node",
      "args": ["~/.antigravity/mcp-github/index.js"],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}
 
// ❌ Common mistakes
// - Trailing comma: "args": ["..."],  ← Invalid
// - Single quotes: 'command' ← Must use double quotes
// - Unset env vars: GITHUB_TOKEN left blank or undefined

Quick debug:

Open the JSON file in your editor
Paste it into an online validator (jsonlint.com)
Fix errors shown
Restart Antigravity

3. Port Conflicts

Multiple MCP servers attempting to use the same port will fail. This often happens when running multiple projects locally.

# Check port usage (macOS/Linux)
lsof -i :3000
 
# Windows
netstat -ano | findstr :3000
 
# Example output if port is in use:
# node    12345  user   20u  IPv4  0x...  0t0  TCP *:3000 (LISTEN)

Solutions:

Kill the conflicting process: kill -9 <PID>
Change the MCP server port in your configuration
Explicitly specify port numbers in Antigravity settings

Antigravity Builder Connection Errors

When "Connection Failed" appears in Builder:

Timeout (30+ seconds): MCP server is slow to start. Check server resources or initial setup
Auth error: Invalid credentials. See the authentication section below
Version mismatch: Builder uses older MCP protocol. Update Antigravity

Authentication & Credentials Issues

Check API Token Expiration

External APIs (GitHub, Figma, Google) use tokens with expiration dates.

GitHub PAT: Expires after 2 years by default
Figma Token: Varies, typically 2+ years
Google OAuth: Refresh tokens valid 6 months

How to fix:

Visit the auth provider (GitHub Settings → Developer settings, etc.)
Check token expiration
Generate a new one if expired
Update mcp.json with the new value
Restart Antigravity

Missing Environment Variables

You may have specified an "env" field but left the actual value blank.

// ❌ Value is empty
{
  "env": {
    "GITHUB_TOKEN": ""
  }
}
 
// ✅ Properly set
{
  "env": {
    "GITHUB_TOKEN": "ghp_..."
  }
}

If using shell env vars, verify before launching Antigravity:

echo $GITHUB_TOKEN
echo $FIGMA_TOKEN

Empty output means you need to add these to .bashrc or .zshrc.

Specific MCP Issues

Figma MCP: "Invalid file permission"

Your Figma API token lacks access to specific files.

Fix:

Go to Figma team settings and check token permissions
Regenerate with "Files" permission enabled
Ensure all target files are accessible

GitHub MCP: "Rate limit exceeded"

GitHub API allows 60 unauthenticated requests/hour, 5,000 authenticated. Heavy repository operations or searches can hit this limit.

Solution:

Check usage: curl -H "Authorization: token YOUR_GITHUB_TOKEN" https://api.github.com/rate_limit
Wait if limit is near
Optimize API calls in your setup

InForge Integration Considerations

When connecting MCP from Antigravity to InForge:

File system access: InForge MCPs may not access files outside the sandbox
Isolated env vars: InForge maintains separate environment variables—desktop Antigravity settings don't carry over
Network restrictions: Some corporate networks block external API access from InForge

InForge MCP setup:

Open your InForge project's "MCP Configuration"
Re-enter authentication credentials for each MCP server
Click "Test Connection"
If errors appear, ask your network admin about firewall rules

Debugging MCP Connections

Step 1: Check Logs

Antigravity outputs detailed logs. Run in debug mode to pinpoint issues.

# Debug mode (if Antigravity has CLI)
ANTIGRAVITY_DEBUG=1 antigravity
 
# Or in the app: View → Logs (desktop)

Look for:

MCP server startup failed
Connection timeout
Invalid credentials
ECONNREFUSED or EADDRINUSE

Step 2: Test Server in Isolation

Verify the MCP server starts on its own.

# If it's a Node.js script
cd ~/.antigravity/mcp-github
node index.js
 
# Success looks like:
# MCP Server listening on port 3001
# Ready to accept connections

Step 3: Connection Test Script

Run this to confirm the MCP server responds:

// test_mcp_connection.js
const net = require('net');
 
const SERVER_HOST = 'localhost';
const SERVER_PORT = 3001;
 
const client = net.createConnection(SERVER_PORT, SERVER_HOST, () => {
  console.log(`✅ Connected to MCP server: ${SERVER_HOST}:${SERVER_PORT}`);
 
  const initMessage = {
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: "2024-11-05"
    }
  };
 
  client.write(JSON.stringify(initMessage) + '\n');
});
 
client.on('data', (data) => {
  console.log(`📨 Server response:\n${data.toString()}`);
  client.destroy();
});
 
client.on('error', (err) => {
  console.error(`❌ Connection failed: ${err.message}`);
  console.error(`Code: ${err.code}`);
});
 
client.setTimeout(5000, () => {
  console.error('❌ Timeout: No response within 5 seconds');
  client.destroy();
});

Run it:

node test_mcp_connection.js

Troubleshooting Checklist

Node.js version: v18+
JSON syntax: Valid format, no trailing commas
API tokens: Not expired, correctly set in env
Ports: No conflicts with other processes
Logs: Reviewed for specific error messages
Isolation test: Server runs standalone
Connection test: Script confirms responsiveness

Looking back

Most MCP connection issues stem from:

Node.js version incompatibility
JSON syntax errors
Expired or missing credentials
Port conflicts
Network/firewall restrictions

By checking logs, testing in isolation, and running the connection script, you can quickly isolate problems. Proper initial configuration pays dividends in smooth, reliable operation later.