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
    }
  }
}