Skip to main content
HUMΛN

Org MCP endpoint

Overview

Every HUMΛN org can expose a hosted MCP endpoint at https://{org_slug}.mcp.haio.run. The Worker merges two tool catalogs:

  1. Platform tools — curated primitives from @human/mcp (human.ask, human.call, developer tools pack, …)
  2. Org mesh tools — workflows, agents, and capability packs registered in your org graph via GET /v1/mcp/tools

Host routing enforces that the delegation's org matches the subdomain (apps/mcp-worker/src/host-routing.ts). A token for did:org:acme cannot call tools on https://other-co.mcp.haio.run.

Why an org endpoint?

  • Capability mesh — installed bundles and workflows appear in tools/list without redeploying the Worker
  • Sovereignty — org-scoped delegations; host slug must match delegation org
  • Same transport — /mcp (Streamable HTTP), /sse + /messages, OAuth discovery on auth.md
  • Local dev parity — HUMAN_ORG_ENDPOINT=https://{slug}.mcp.haio.run for npx @human/mcp

Think of it like: Your org's API gateway for AI clients — one URL, governed tools, Passport delegation at the door.

Shipped surfaces

Host MCP base Discovery
Personal / platform https://mcp.haio.run GET /auth.md
Org workspace https://{org_slug}.mcp.haio.run GET /.well-known/oauth-authorization-server
Staging https://{org_slug}.mcp-staging.haio.run Same shape as production
API Purpose
GET /v1/mcp/tools Org capability graph → MCP tool definitions (Worker caches ~60s)
POST /v1/mcp/proxy Fallback when a tool is in @human/mcp but not in the Worker catalog
POST /v1/mcp-sessions/register Worker registers Streamable HTTP sessions (internal)

Code: apps/mcp-worker/src/org-tools.ts, packages/mcp/src/server.ts (stdio bridge).

Try it

>
SDK:

Claude Code hosted config

{
  "mcpServers": {
    "human-org": {
      "url": "https://YOUR_ORG_SLUG.mcp.haio.run/mcp",
      "headers": {
        "Authorization": "Bearer <org-scoped delegation>"
      }
    }
  }
}

Host mismatch (403)

If you see Host org slug "foo" does not match delegation org, mint a delegation for the org that owns foo, or use the bare mcp.haio.run host for personal workspace tokens.

Use cases

  1. Org-specific workflows in Cursor — install a bundle; its tools appear on {slug}.mcp.haio.run for every developer with scope.
  2. Claude Code without npx — Streamable HTTP URL + OAuth PKCE; no local stdio process.
  3. Capability pack publishing — marketplace pack installs register tools into the org mesh automatically.
  4. Multi-tenant SaaS — each customer org gets an isolated MCP surface; delegations cannot cross hosts.

Security considerations

DO

Use org-scoped delegations on org hosts

Review tools/list output before granting broad agent autonomy

Revoke delegations in Console when offboarding team members

DON'T

Do not reuse personal tokens against org subdomains

Do not disable scope checks by calling api.haio.run directly from untrusted clients without delegation

Do not assume org tools when platform host is used — mesh tools require org_id on token

See also

← All patterns