BinaSmart

BinaSmart MCP server

The public Model Context Protocol server for BinaSmart (bina.et), Ethiopia's all-in-one platform. Any MCP-capable assistant (Claude, ChatGPT, Gemini and others) can use it to:

• Ride in Addis Ababa: quote fixed fares, book a ride (the user confirms first), check its status, cancel it
• Find places: buildings, hotels, hospitals and clinics, shops and restaurants, with their bina.et pages
• Jobs and tenders: open vacancies by field or city (Amharic or English), employers, open tenders with deadlines. Vacancies show as job cards in assistants that support MCP Apps
• Working abroad: licensed Ethiopian overseas employment agencies and their GCC partner offices
• Homes and cars: properties for sale or rent, cars for sale
• Guides and news: the bilingual Digital Ethiopia guides (Fayda, passport, telebirr, tax, …) and Amharic news
• BinaPool: shared commute corridors and groups

Endpoint: https://bina.et/mcp (Streamable HTTP, stateless, no sign-in needed) Registry: et.bina/binasmart on the MCP Registry Docs: GET https://bina.et/mcp · health: https://bina.et/mcp/health

Claude plugin

The plugin/ folder is a Claude plugin: the same MCP server plus five skills that show Claude how to use it for rides, jobs, paperwork, places and tenders. It contains no code, only Markdown skills and one MCP server entry.

Connect

In any client that accepts a remote MCP server, add the URL https://bina.et/mcp. For example, in Claude: *Settings → Connectors → Add custom connector*.

How it is built

• mcp-server/server.mjs: the MCP endpoint (Express + @modelcontextprotocol/sdk)
• mcp-server/tools/: one file per tool group (ride, directory, jobs, health, market, content, guides, knowledge, agencies)
• mcp-server/widgets/ and mcp-server/lib/widgets.mjs: the job-card page (MCP Apps) served as ui://bina/jobs-v1.html, with the @modelcontextprotocol/ext-apps browser bundle inlined
• mcp-server/lib/: phone normalisation, an idempotency key so retries never double-book, a per-caller rate limiter, the ride API client
• api/ and hotels/rules.js: the shared usage meter, API-key check and hotel rules from the main BinaSmart app, which this server imports

The server runs next to the private BinaSmart application and reads its data and settings at runtime (database, ride API on localhost, the .env file). No credentials are in this repository. So this code documents exactly what the public endpoint does, but on its own it will not run against BinaSmart data.

Safety

• request_ride and cancel_ride are marked as write tools (readOnlyHint: false), so clients ask the user before calling them.
• The job-card page only reads the tool result: it opens bina.et links through the host and can reach no other site.
• Reviewers can test request_ride with the reserved number 0900000099: it returns a clearly marked test booking and no driver is sent.
• Bookings are limited per phone (5 per 10 minutes) and per caller (10 per hour). Retries with the same details within 10 minutes return the same booking instead of a second one.
• Only Ethiopian phone numbers are accepted for rides. Phone numbers are masked in logs.
• Privacy: bina.et/privacy · Terms: bina.et/terms · Support: bina.et/support

Standalone (tool definitions only)

node mcp-server/stdio.mjs starts the same tools over stdio without the BinaSmart database or .env, so MCP directories such as Glama can build it in their own container and read the tool definitions. Calls that need live data return an error pointing to https://bina.et/mcp.

Tests

cd mcp-server && npm install && node --test test/*.test.mjs

The tests use reserved test phone numbers only.

Licence

MIT. See LICENSE. © 2026 BinaSmart (Ibrahim Kedir).