Forge Geoapify MCP Server

Remote MCP server for Forge Lead Engine discovery.

It exposes exactly two tools:

• search_businesses
• get_business_details

Security model

• GEOAPIFY_API_KEY stays only on the server.
• Fleet authenticates to the MCP server with Authorization: Bearer <MCP_AUTH_TOKEN>.
• The server never exposes the Geoapify secret in tool outputs, logs, or error bodies.

What it does

• Searches Geoapify Places for candidate businesses.
• Normalizes only fields actually returned by Geoapify.
• Deduplicates by place ID and stable business/location fingerprints.
• Supports pagination, retries, rate-limit handling, timeouts, and malformed-response handling.
• Returns records for downstream Exa verification, Apollo enrichment, qualification, and scoring.
• Keeps outbound email, WhatsApp, follow-ups, and any sales sending disabled.

Important workflow rule

A missing website from Geoapify does not mean the business has no website.

Downstream pipeline should be:

Geoapify discovery → dedupe → Exa website verification → Apollo contact enrichment → qualification → scoring → research → approval queue

No outbound email / WhatsApp behavior is included in this server.

Local run

1. Install dependencies:

   npm install
   

2. Copy environment file:

   cp .env.example .env
   

3. Set GEOAPIFY_API_KEY and MCP_AUTH_TOKEN in .env.

4. Start the server:

   npm run dev
   

5. Health check:

   curl -s http://localhost:8787/healthz
   

6. MCP endpoint:

   curl -s -H "Authorization: Bearer $MCP_AUTH_TOKEN" http://localhost:8787/mcp
   

Deployment

Recommended easy hosting

Use Render for the simplest free/easy setup.

Steps

1. Create a web service from this repository.
2. Set environment variables:
   • GEOAPIFY_API_KEY
   • MCP_AUTH_TOKEN
3. Use the Dockerfile or build command:
   • Build: npm install && npm run build
   • Start: npm start
4. Ensure HTTPS is enabled.
5. Expose /mcp and /healthz.

Recommended URL format

• Base: https://<your-service-domain>
• MCP endpoint: https://<your-service-domain>/mcp
• Health: https://<your-service-domain>/healthz

Fleet custom MCP configuration

Use a Custom MCP server with:

• URL: https://<your-service-domain>/mcp
• Auth mode: Static Headers
• Header: Authorization: Bearer <MCP_AUTH_TOKEN>

Do not paste GEOAPIFY_API_KEY into Fleet. It stays only in the remote server environment.

Health check

The health endpoint should return:

{ "ok": true }

If the server is behind a platform health probe, point it at /healthz.

Manual MCP test request

After deployment, the exact discovery test request is:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_businesses",
    "arguments": {
      "country": "UAE",
      "city": "Dubai",
      "category": "dental clinics",
      "max_results": 10
    }
  }
}