@hamolus/mcp

Deploy to Cloudflare

That button forks this repository into your own GitHub account, names the Worker, provisions the KV namespace, D1 database and R2 bucket on your account, and wires up Workers Builds so later pushes deploy themselves.

Register it before anything works. A fresh deploy has an empty MCP_INSTANCE_ID, so it runs on the deprecated path with no credential and answers every tool call with a configuration error. Create the instance in the core console under Environment → MCP, then set its id as a var:

# Settings → Variables and Secrets, or:
# wrangler deploy --var MCP_INSTANCE_ID: --var CORE_API_URL:https:///api

Callers then present a per-user token from the console as Authorization: Bearer …. CORE_API_URL ships as http://localhost:8787/api, so an online deploy has to be pointed at your core.

If every call fails with CORE_UNAVAILABLE and a 404, your account cannot reach workers.dev from inside the Workers runtime — the URL is correct and editing it will not help. Add a service binding to the core instead:

"services": [{ "binding": "CORE", "service": "" }]

It is in wrangler.jsonc commented out: leave it out for wrangler dev, where the local core is a separate process on http://localhost:8787.

Model Context Protocol server for Hamolus. It exposes the core API — collections, records, media, files, panels, lands — as MCP tools, resources and prompts over Streamable HTTP on Cloudflare Workers, so an AI agent can read and write your data directly.

Use it

hamolus add mcp        # copy this server into ./mcp

Configure

Two vars. There are no secrets.

Everything else is per-instance configuration in the core: which colony the server serves, whether it is enabled, whether it is read-only, which tool groups it offers, and which collections get generated tools. Read it from GET /api/_mcp/config at request time and change it from the console — no redeploy, no secret to rotate.

Callers send a per-user token issued in the console as Authorization: Bearer . The core exchanges it for a short-lived scoped session, and each token can be revoked on its own. Stored hashes only; the plaintext is shown once, at creation.

MCP_INSTANCE_ID is a credential rather than a label — anyone holding it can read this server’s configuration — so it is generated rather than chosen. GET / echoes it, plus