Firecrawl Agent MCP Server

Instructions

Implementation Reference

• src/services/firecrawl-client.ts:65-95 (handler)

  Core handler that implements agent_start by POSTing the agent request to Firecrawl API /v1/agent/start endpoint and returning the job ID.

  async startAgent(request: FirecrawlAgentRequest): Promise<FirecrawlAgentResponse> {
    try {
      const response = await fetch(`${this.apiBase}/v1/agent/start`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.apiKey}`,
        },
        body: JSON.stringify(request),
      });
  
      const data = await response.json() as any;
  
      if (!response.ok) {
        return {
          success: false,
          error: data.error || `HTTP ${response.status}: ${response.statusText}`,
        };
      }
  
      return {
        success: true,
        id: data.id,
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error',
      };
    }
  }

• src/server.ts:269-313 (handler)

  MCP server tool call handler for 'agent_start': destructures arguments, calls FirecrawlClient.startAgent, formats response with jobId or error.

  case 'agent_start': {
    const { prompt, urls, schema, maxCredits } = args as {
      prompt: string;
      urls?: string[];
      schema?: Record<string, any>;
      maxCredits?: number;
    };
  
    const result = await firecrawl.startAgent({
      prompt,
      urls,
      schema,
      maxCredits,
    });
  
    if (!result.success) {
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${result.error}`,
          },
        ],
        isError: true,
      };
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              success: true,
              jobId: result.id,
              message:
                'Agent job started. Use agent_status with this jobId to check progress.',
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/server.ts:89-120 (schema)

  MCP tool schema definition for agent_start, including name, description, and JSON inputSchema matching FirecrawlAgentRequest.

  {
    name: 'agent_start',
    description:
      'Start a Firecrawl Agent job asynchronously. Returns a job ID immediately without waiting for completion. Use this for long-running research tasks. Poll with agent_status to check progress.',
    inputSchema: {
      type: 'object',
      properties: {
        prompt: {
          type: 'string',
          description:
            'Describe what data you want to extract. Be specific about what information you need.',
        },
        urls: {
          type: 'array',
          items: { type: 'string' },
          description:
            'Optional: Specific URLs to search. If not provided, agent will search the web.',
        },
        schema: {
          type: 'object',
          description:
            'Optional: JSON schema for structured output. Define the exact structure you want the data returned in.',
        },
        maxCredits: {
          type: 'number',
          description:
            'Optional: Maximum credits to spend on this request. Use to control costs.',
        },
      },
      required: ['prompt'],
    },
  },

• src/types/firecrawl.ts:6-11 (schema)

  TypeScript interface defining the input parameters for agent_start, used in FirecrawlClient.startAgent.

  export interface FirecrawlAgentRequest {
    prompt: string;
    schema?: Record<string, any>;
    urls?: string[];
    maxCredits?: number;
  }

• src/server.ts:215-217 (registration)

  Registers the ListTools handler that exposes the agent_start tool via the TOOLS array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools: TOOLS };
  });