Hebline MCP Server

Your smartest line to any API.

MCP gave agents a language. Hebline gives them judgment. It sits between your AI agents and the APIs they call — routing every request to the best service at the best price, including free alternatives. Every call makes it smarter.

Why Hebline?

Your agents are bleeding money. One task triggers 5–10 paid API calls across different providers. No transparency, no cost control. Hebline fixes that:

• Free by default — Always a free or open-source alternative in the mix. No key needed to get started.
• A broker that thinks — Scores every service on quality, cost, latency, and reliability. Picks the best one automatically.
• Provider Abstraction — Your agent says what it needs ("geocode this address"), not which service to use. Swap providers without changing agent code.
• Cost Transparency — Every call is logged with service used, latency, and cost. Know exactly what your agents spend.
• Learns from usage — Hebbian learning strengthens what works, weakens what doesn't. Your broker gets smarter every day.
• BYOK (Bring Your Own Key) — Paid services use your API keys via environment variables. No key? The service is automatically excluded from routing.
• GDPR compliant — Only anonymized metadata logged. No API call content stored. Self-hosted option for zero data leaving your network.
• Open Source — Core MCP server is MIT licensed. Community-driven adapter system.

How It Works

Your AI Agent ←→ Hebline MCP Server ←→ Best API (Nominatim, DeepL, Google Maps, ...)
                        │
                   Smart Routing
                   Cost Logging
                   Provider Scoring

Your agent connects to Hebline as an MCP server. Instead of calling APIs directly, it uses Hebline's tools — execute, compare, or categories. Hebline scores all available services, picks the best one, makes the call, and returns the result with full metadata.

Available MCP Tools

Tool	Description
execute	Route to the best service and make the API call. Returns result + metadata (service, cost, latency).
compare	Show all available services for a capability with scores. See what's available before committing.
categories	List all supported capabilities and their services.

Quick Start

Add to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hebline": {
      "command": "npx",
      "args": ["-y", "-p", "@hebline.ai/mcp-server", "hebline-mcp"]
    }
  }
}

Add to Claude Code

Add to .mcp.json:

{
  "mcpServers": {
    "hebline": {
      "command": "hebline-mcp"
    }
  }
}

Add to Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "hebline": {
      "command": "npx",
      "args": ["-y", "-p", "@hebline.ai/mcp-server", "hebline-mcp"]
    }
  }
}

Add to Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "hebline": {
      "command": "npx",
      "args": ["-y", "-p", "@hebline.ai/mcp-server", "hebline-mcp"]
    }
  }
}

Add to VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "hebline": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@hebline.ai/mcp-server", "hebline-mcp"]
    }
  }
}

Install globally

npm install -g @hebline.ai/mcp-server

With paid services (optional)

Set environment variables for any paid providers you want to use:

GOOGLE_MAPS_API_KEY=your-key-here
DEEPL_API_KEY=your-key-here
LIBRETRANSLATE_API_KEY=your-key-here

No keys? No problem — Hebline routes to free alternatives automatically.

Supported Services

Category	Service	Free	API Key Required
Geocoding	Nominatim (OpenStreetMap)	Yes	No
Geocoding	Google Maps	No	GOOGLE_MAPS_API_KEY
Translation	MyMemory	Yes	No
Translation	LibreTranslate	No	LIBRETRANSLATE_API_KEY
Translation	DeepL	No	DEEPL_API_KEY

Example

An agent asks: "Geocode the Brandenburg Gate in Berlin"

Hebline receives:

{
  "capability": "geocoding",
  "input": { "query": "Brandenburger Tor, Berlin" },
  "constraint": "free"
}

Hebline responds:

{
  "success": true,
  "data": {
    "lat": 52.5163,
    "lon": 13.3777,
    "displayName": "Brandenburger Tor, Pariser Platz, Berlin, 10117, Deutschland"
  },
  "meta": {
    "service": "Nominatim (OpenStreetMap)",
    "costUsd": 0,
    "latencyMs": 258,
    "score": 0.702,
    "free": true
  }
}

The agent got coordinates, knows it was free, and Hebline logged the call for future analysis.

Architecture

mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point (stdio transport)
│   ├── types.ts              # Shared TypeScript types
│   ├── registry.ts           # Service definitions (capabilities, costs, scores)
│   ├── router.ts             # Weighted scoring engine (Hopfield-ready)
│   ├── logger.ts             # Append-only JSONL call log (~/.hebline/calls.jsonl)
│   ├── adapters/             # One adapter per service
│   │   ├── nominatim.ts      # Free geocoding
│   │   ├── google-maps.ts    # Paid geocoding (BYOK)
│   │   ├── mymemory.ts       # Free translation
│   │   ├── libretranslate.ts # Paid translation (BYOK)
│   │   └── deepl.ts          # Paid translation (BYOK)
│   └── tools/                # MCP tool definitions
│       ├── execute.ts        # Route + call best service
│       ├── compare.ts        # Score all services
│       └── categories.ts     # List capabilities

Call Logging

Every API call is logged to ~/.hebline/calls.jsonl:

{"timestamp":"2026-03-29T09:36:37Z","capability":"geocoding","serviceId":"nominatim","latencyMs":212,"success":true,"costUsd":0}

No content is logged — only metadata. This data will power Hebbian Learning in future versions.

Roadmap

• [x] Core MCP server with stdio transport
• [x] Weighted scoring router
• [x] Geocoding adapters (Nominatim, Google Maps)
• [x] Translation adapters (MyMemory, LibreTranslate, DeepL)
• [x] BYOK key management
• [x] Append-only call logging
• [x] CI/CD with GitHub Actions
• [ ] Hebbian Learning — router learns from call history
• [ ] Hopfield network scoring (replaces weighted scoring)
• [ ] More categories (web scraping, currency, OCR, email)
• [ ] Community adapter system
• [ ] SSE transport for remote deployments
• [ ] Web dashboard for cost analytics
• [ ] Budget alerts and spending limits
• [ ] Multi-agent cost attribution

Contributing

Contributions are welcome! Adding a new adapter is straightforward — implement the ServiceAdapter interface and register it.

git clone https://github.com/hebline/mcp-server.git
cd mcp-server
npm install
npm run build
npm test

License

MIT

---

Built by Hebline — Your smartest line to any API.