Remote MCP server on Cloudflare Workers exposing two tools, search and execute, over a
unified catalog of Stellar ecosystem services and skills. Agents use search to discover
capabilities, then call execute with JavaScript that runs in a Dynamic Worker isolate with no
network access; service calls go through host-side adapters. The server instructions also include
a generated source-family micro-map so agents can plan which catalog family should ground a
question before searching.
Design: PLAN.md. Code-verified mechanics and operating limits: ARCHITECTURE.md.
Deployed as the Cloudflare worker stellar-raven-codemode at https://raven.stellar.org — the
worker/service name deliberately keeps the codemode suffix even though the repo is stellar-raven.
Server URL: https://raven.stellar.org (canonical since 2026-08-04; service live since 2026-07-02)
MCP endpoint: POST https://raven.stellar.org/mcp (streamable HTTP)
Aliases: https://raven.stellar.buzz and https://agents.stellar.buzz still serve the same
worker (`/mcp` included) — kept for existing clients.
Health: GET /health # service heartbeat
GET /health/skills # last skill-retrieval canary verdict (503 = failing/never ran)
Local dev: use Node 24, run npm ci, populate .dev.vars, then npm run dev and point a client at
http://localhost:8787/mcp. Note: wrangler dev does NOT hot-reload .dev.vars edits —
restart it after changing them.
Add https://raven.stellar.org/mcp in an MCP client that supports streamable HTTP and OAuth
(Claude, Cursor, or any compatible client). The Worker is its own OAuth authorization server and
hands sign-in to WorkOS AuthKit; clients should discover and complete that flow automatically.
Access tokens last 1 hour, and compatible clients refresh them automatically within a fixed
90-day authorization window before browser authorization is required again.
Operators can manage non-expiring, full-access named credentials in production OAUTH_KV:
npm run mcp-key -- create admin
npm run mcp-key -- rotate admin --out /tmp/stellar-raven-admin.credential
npm run mcp-key -- revoke adminNames match [a-z][a-z0-9-]{0,31}. Create and rotate emit the credential once after the
remote write; --out writes it with mode 0600. Send it as
Authorization: Bearer <name>:<token>. Cloudflare KV changes can take 60 seconds or longer to
propagate globally, so this is for infrequently changed internal keys, not immediate emergency
revocation. See Cloudflare KV consistency.
Operational auth details live in ARCHITECTURE.md and
research/auth-workos.md. Vulnerability reporting and researcher
scope live in SECURITY.md.
# use Node 24, matching CI
npm ci
npm run typecheck # tsc
npm test # vitest (offline; auth suite in test/auth.test.ts)
npm run typegen # regenerate env.d.ts after wrangler.jsonc/.dev.vars changes
For local MCP testing, populate .dev.vars, run npm run dev, and point a client at
http://localhost:8787/mcp. Restart wrangler dev after editing .dev.vars.
Structured JSON events (src/observability.ts) land in Workers Logs; traces are enabled with a
custom codemode.execute span around each sandbox run (the Worker Loader isolate is not
auto-instrumented). Both are queryable in the dash (Workers & Pages → Observability) or via the
telemetry query API. Survey of the whole surface — pricing, query API, OTel export, GraphQL
metrics: research/observability-cloudflare.md.
For cap/rate-limit reviews, start with ARCHITECTURE.md §7: it lists the shared execute sandbox limits, demo-only chat limits, MCP-only artifact/auth limits, and the log event names to query.
Apache-2.0 © 2026 Tyler van der Hoeven — except vendored third-party code in
src/catalog/vendor/, which retains its upstream license. Ecosystem skill bodies are not
vendored here at all: this repo commits only their pinned addresses (upstream commit + git blob
hash) and fetches each file from its own upstream, verified, at build and read time. See
THIRD-PARTY-NOTICES.md.