Articles/Integrations

⬡ Integrations/2026-03-30Advanced

Antigravity × Custom MCP Server Production Guide— Building External Tool Integrations at Scale

Build production-grade custom MCP servers for Antigravity: architecture design, authentication, rate limiting, error handling, testing, and deployment patterns for integrating external APIs and internal tools.

antigravity⁴⁶¹ mcp¹⁵serverproduction⁷¹ integration⁷ advanced²⁰

✦ Premium Article

Setup and context — How MCP Transforms the Development Experience

MCP (Model Context Protocol) is the standard protocol connecting AI agents to external tools. Antigravity's AI agents can access databases, call external APIs, and manipulate files directly from the IDE through MCP servers.

While official MCP servers (GitHub, Slack, Notion, etc.) are convenient, integrating with company-specific internal tools and proprietary APIs requires building custom MCP servers. This guide covers the complete journey from TypeScript server design through authentication, error handling, testing, and deployment — all at production quality.

We assume familiarity with MCP server fundamentals. If you're new to MCP, start there first.

MCP Server Architecture Design

Here are the architectural principles that underpin robust production MCP servers.

Layered Architecture

An effective MCP server uses three distinct layers:

Protocol layer: Handles MCP-compliant request/response processing, tool definitions, validation, and serialization
Business logic layer: Implements actual tool functionality — external API calls, data transformation, cache management
Infrastructure layer: Cross-cutting concerns including authentication, rate limiting, logging, and health checks

// Project structure
// src/
// ├── server.ts          — MCP server entry point
// ├── tools/             — Tool definitions and implementations
// │   ├── index.ts
// │   ├── database.ts    — Database operations
// │   └── api-client.ts  — External API calls
// ├── middleware/         — Auth, rate limiting, logging
// │   ├── auth.ts
// │   ├── rate-limit.ts
// │   └── logger.ts
// └── config/            — Configuration management
//     └── index.ts

Tool Definition Best Practices

When defining MCP tools, writing clear descriptions and strict input schemas is critical for the AI agent to select and use tools correctly.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
 
const server = new McpServer({
  name: "company-internal-tools",
  version: "1.0.0",
});
 
// Tool: Internal knowledge base search
server.tool(
  "search_knowledge_base",
  // Description helps the agent decide when to use this tool
  "Search the company's internal knowledge base for technical documentation, " +
  "runbooks, and architecture decision records. Returns relevant documents " +
  "with titles, snippets, and relevance scores. Use this when the user asks " +
  "about internal processes, system architecture, or troubleshooting steps.",
  {
    // Strict schema with zod
    query: z.string().describe("Search query in natural language"),
    category: z.enum(["runbook", "adr", "api-doc", "onboarding"])
      .optional()
      .describe("Filter by document category"),
    limit: z.number().min(1).max(20).default(5)
      .describe("Maximum number of results to return"),
  },
  async ({ query, category, limit }) => {
    // Delegate to business logic layer
    const results = await knowledgeBase.search(query, { category, limit });
 
    return {
      content: [{
        type: "text",
        text: JSON.stringify(results, null, 2),
      }],
    };
  }
);

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Master MCP server architecture design and TypeScript implementation from scratch to production quality

✦Understand essential security patterns including authentication, rate limiting, and input sanitization

✦Apply real-world integration patterns with Slack, GitHub, and internal tools to your own projects immediately

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Authentication and Security Implementation

Access control for MCP servers is non-negotiable in production. Here are patterns for token-based auth, permission management, and input validation.

Token-Based Authentication Middleware

// src/middleware/auth.ts
interface AuthConfig {
  tokenHeader: string;
  validTokens: Set<string>;
  allowedTools?: Map<string, string[]>; // token -> allowed tool names
}
 
function createAuthMiddleware(config: AuthConfig) {
  return async (request: McpRequest, next: () => Promise<McpResponse>) => {
    const token = request.headers?.[config.tokenHeader];
 
    if (!token || !config.validTokens.has(token)) {
      return {
        error: {
          code: -32001,
          message: "Authentication required. Provide a valid API token.",
        },
      };
    }
 
    // Tool-level permission check
    if (config.allowedTools && request.method === "tools/call") {
      const toolName = request.params?.name;
      const allowed = config.allowedTools.get(token) || [];
      if (!allowed.includes(toolName)) {
        return {
          error: {
            code: -32002,
            message: `Token does not have permission to use tool: ${toolName}`,
          },
        };
      }
    }
 
    return next();
  };
}

Input Sanitization

Inputs generated by AI agents can include unexpected formats or malicious payloads. Always implement SQL injection and command injection prevention.

// src/tools/database.ts
import { z } from "zod";
 
// SQL injection prevention: only allow parameterized queries
server.tool(
  "query_metrics",
  "Query application metrics from the analytics database. " +
  "Supports filtering by date range, metric name, and environment.",
  {
    metric_name: z.enum([
      "page_views", "api_latency", "error_rate",
      "active_users", "conversion_rate"
    ]).describe("The metric to query"),
    start_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
      .describe("Start date in YYYY-MM-DD format"),
    end_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
      .describe("End date in YYYY-MM-DD format"),
    environment: z.enum(["production", "staging"]).default("production"),
  },
  async ({ metric_name, start_date, end_date, environment }) => {
    // Parameterized query prevents SQL injection
    const rows = await db.query(
      `SELECT date, value FROM metrics
       WHERE metric_name = $1
         AND date BETWEEN $2 AND $3
         AND environment = $4
       ORDER BY date`,
      [metric_name, start_date, end_date, environment]
    );
 
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          metric: metric_name,
          period: `${start_date} to ${end_date}`,
          data_points: rows.length,
          results: rows,
        }, null, 2),
      }],
    };
  }
);

Rate Limiting and Resource Management

Prevent your MCP server from overloading external APIs or databases with proper rate limiting.

// src/middleware/rate-limit.ts
class SlidingWindowRateLimiter {
  private windows: Map<string, number[]> = new Map();
 
  constructor(
    private maxRequests: number,
    private windowMs: number,
  ) {}
 
  check(key: string): { allowed: boolean; retryAfterMs?: number } {
    const now = Date.now();
    const timestamps = this.windows.get(key) || [];
 
    // Remove timestamps outside the window
    const valid = timestamps.filter(t => now - t < this.windowMs);
    this.windows.set(key, valid);
 
    if (valid.length >= this.maxRequests) {
      const oldestInWindow = valid[0];
      const retryAfterMs = this.windowMs - (now - oldestInWindow);
      return { allowed: false, retryAfterMs };
    }
 
    valid.push(now);
    return { allowed: true };
  }
}
 
// Different rate limits per tool
const rateLimiters = {
  search_knowledge_base: new SlidingWindowRateLimiter(30, 60_000),  // 30/min
  query_metrics: new SlidingWindowRateLimiter(10, 60_000),          // 10/min
  deploy_service: new SlidingWindowRateLimiter(2, 300_000),         // 2/5min
};

Error Handling and Retry Strategies

Design external API calls with failure as the default assumption. Return structured error messages so agents can respond appropriately.

// src/tools/api-client.ts
interface ToolError {
  recoverable: boolean;
  message: string;
  suggestion?: string;
  retryAfterMs?: number;
}
 
async function withRetry<T>(
  fn: () => Promise<T>,
  options: {
    maxRetries: number;
    baseDelayMs: number;
    maxDelayMs: number;
  } = { maxRetries: 3, baseDelayMs: 1000, maxDelayMs: 10000 }
): Promise<T> {
  let lastError: Error | null = null;
 
  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;
      if (attempt === options.maxRetries) break;
 
      // Exponential backoff with jitter
      const delay = Math.min(
        options.baseDelayMs * Math.pow(2, attempt) + Math.random() * 1000,
        options.maxDelayMs
      );
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
 
  throw lastError;
}
 
// Structured error response for agents
function formatToolError(error: ToolError) {
  return {
    content: [{
      type: "text",
      text: JSON.stringify({
        status: "error",
        recoverable: error.recoverable,
        message: error.message,
        suggestion: error.suggestion,
        retry_after_ms: error.retryAfterMs,
      }),
    }],
    isError: true,
  };
}

Practical Example — Slack + GitHub Issues Integration

Here's a concrete implementation that combines Slack notifications with GitHub Issue creation into a single incident response tool.

// src/tools/incident-response.ts
server.tool(
  "create_incident",
  "Create an incident report that simultaneously files a GitHub Issue " +
  "and sends a notification to the team's Slack channel. Use this when " +
  "a production issue is detected and needs immediate team awareness.",
  {
    title: z.string().min(5).max(200),
    severity: z.enum(["critical", "high", "medium", "low"]),
    description: z.string().min(20),
    affected_services: z.array(z.string()).min(1),
  },
  async ({ title, severity, description, affected_services }) => {
    // Parallel execution to reduce latency
    const [githubResult, slackResult] = await Promise.allSettled([
      createGitHubIssue({
        title: `[${severity.toUpperCase()}] ${title}`,
        body: `## Incident Report\n\n${description}\n\n**Affected Services:** ${affected_services.join(", ")}`,
        labels: ["incident", severity],
      }),
      sendSlackNotification({
        channel: severity === "critical" ? "#incidents-critical" : "#incidents",
        text: `🚨 *${severity.toUpperCase()} Incident*: ${title}\n${description}`,
      }),
    ]);
 
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          github_issue: githubResult.status === "fulfilled"
            ? { url: githubResult.value.html_url, number: githubResult.value.number }
            : { error: "Failed to create GitHub Issue" },
          slack_notification: slackResult.status === "fulfilled"
            ? { sent: true, channel: slackResult.value.channel }
            : { error: "Failed to send Slack notification" },
        }, null, 2),
      }],
    };
  }
);

This integration pattern works well with the Manager Surface approach described in the Multi-Agent Architecture Design Guide.

Testing and Debugging

Test MCP servers using a combination of MCP Inspector and unit tests to verify tool behavior.

// tests/tools/knowledge-base.test.ts
import { describe, it, expect, vi } from "vitest";
 
describe("search_knowledge_base tool", () => {
  it("returns results for a valid query", async () => {
    const mockSearch = vi.fn().mockResolvedValue([
      { title: "Deploy Guide", snippet: "Steps to deploy...", score: 0.95 },
    ]);
 
    const result = await searchKnowledgeBase({
      query: "how to deploy",
      limit: 5,
    }, { search: mockSearch });
 
    expect(result.content[0].type).toBe("text");
    const parsed = JSON.parse(result.content[0].text);
    expect(parsed).toHaveLength(1);
    expect(parsed[0].title).toBe("Deploy Guide");
  });
 
  it("returns an empty array when no results are found", async () => {
    const mockSearch = vi.fn().mockResolvedValue([]);
 
    const result = await searchKnowledgeBase({
      query: "nonexistent topic",
      limit: 5,
    }, { search: mockSearch });
 
    const parsed = JSON.parse(result.content[0].text);
    expect(parsed).toHaveLength(0);
  });
 
  it("returns a structured error on database failure", async () => {
    const mockSearch = vi.fn().mockRejectedValue(new Error("Connection timeout"));
 
    const result = await searchKnowledgeBase({
      query: "test",
      limit: 5,
    }, { search: mockSearch });
 
    expect(result.isError).toBe(true);
    const parsed = JSON.parse(result.content[0].text);
    expect(parsed.recoverable).toBe(true);
  });
});

Deployment and Monitoring

For production deployment, containerization with health checks is recommended.

# Dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run build
 
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./
 
# Health check endpoint
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3100/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
 
EXPOSE 3100
CMD ["node", "dist/server.js"]

Combine this with Antigravity's debugging tools to efficiently validate MCP server behavior during development.

A Note from an Indie Developer

Key Takeaways

Building custom MCP servers with Antigravity's protocol dramatically extends what AI agents can do. By combining the layered architecture, authentication and rate limiting, structured error handling, and testing strategies covered in this guide, you can safely operate production-quality MCP servers.

Start by wrapping a single internal API as an MCP server, then incrementally add more tools as your team gains confidence.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.