Frontrun MCP Server

Instructions

Implementation Reference

• index.js:169-177 (handler)

  Handler function for frontrun_convergence tool. Builds query parameters (threshold, since) and makes a GET request to the /v1/convergence API endpoint, returning JSON-formatted results.

    async ({ threshold, since }) => {
      const params = new URLSearchParams();
      if (threshold) params.set('threshold', String(threshold));
      if (since) params.set('since', since);
      const qs = params.toString();
      const result = await apiCall('GET', `/convergence${qs ? '?' + qs : ''}`);
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    }
  );

• index.js:165-168 (schema)

  Zod schema defining two optional input parameters: threshold (number) for minimum tracked accounts, and since (string) for the time window.

  {
    threshold: z.number().optional().describe('Minimum number of tracked accounts that must have followed. Default: 2. Use 3+ for high-conviction signals.'),
    since: z.string().optional().describe('Time window: "48h", "7d", "14d", "30d", or ISO date. Default: "7d"'),
  },

• index.js:161-177 (registration)

  Complete tool registration for frontrun_convergence using MCP server.tool() method. Registers the tool name, description, input schema, and handler function.

  // --- GET /v1/convergence ---
  server.tool(
    'frontrun_convergence',
    'Detect convergence: entities followed by multiple tracked accounts independently within a time window. Higher threshold = stronger signal. This is the highest-signal endpoint — when 3+ VCs independently follow the same account, it strongly suggests pre-funding interest.',
    {
      threshold: z.number().optional().describe('Minimum number of tracked accounts that must have followed. Default: 2. Use 3+ for high-conviction signals.'),
      since: z.string().optional().describe('Time window: "48h", "7d", "14d", "30d", or ISO date. Default: "7d"'),
    },
    async ({ threshold, since }) => {
      const params = new URLSearchParams();
      if (threshold) params.set('threshold', String(threshold));
      if (since) params.set('since', since);
      const qs = params.toString();
      const result = await apiCall('GET', `/convergence${qs ? '?' + qs : ''}`);
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
    }
  );

• index.js:29-73 (helper)

  Helper function apiCall that handles all HTTP requests to the Frontrun API. Includes authentication headers, timeout handling (60s), and error handling for rate limits, auth failures, and insufficient balance.

  async function apiCall(method, path, body = null) {
    const url = `${API_URL}/v1${path}`;
    const options = {
      method,
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
      },
    };
    if (body) {
      options.body = JSON.stringify(body);
    }
  
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 60000);
    options.signal = controller.signal;
  
    let response;
    try {
      response = await fetch(url, options);
    } catch (err) {
      clearTimeout(timeout);
      if (err.name === 'AbortError') return { error: 'Request timed out (60s). Try a narrower query.' };
      return { error: `Network error: ${err.message}` };
    }
    clearTimeout(timeout);
  
    if (response.status === 429) {
      const retry = response.headers.get('Retry-After') || '60';
      return { error: `Rate limited. Retry in ${retry}s.` };
    }
    if (response.status === 401) {
      return { error: 'Invalid API key. Check FRONTRUN_API_KEY.' };
    }
    if (response.status === 402) {
      const data = await response.json();
      return { error: 'Insufficient balance', ...data };
    }
    if (!response.ok) {
      const text = await response.text();
      return { error: `HTTP ${response.status}: ${text.slice(0, 500)}` };
    }
  
    return response.json();
  }