DocsBuildAPI ReferenceSDK Reference

Hosted MCP quickstart

Primary endpoint (Streamable HTTP): https://YOUR_ORG_SLUG.mcp.haio.run/mcp

SSE transport: https://YOUR_ORG_SLUG.mcp.haio.run/sse

Any MCP-compatible client can connect to HUMΛN's hosted Companion in four lines of config.

Cursor (local stdio — preferred for IDE)

{
  "mcpServers": {
    "human": {
      "command": "npx",
      "args": ["-y", "@human/mcp"],
      "env": {
        "HUMAN_API_URL": "https://api.haio.run",
        "HUMAN_DELEGATION_TOKEN": "<delegation-token>"
      }
    }
  }
}

Claude Code (hosted Streamable HTTP)

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

Continue, Zed, Cline, Goose

Use Streamable HTTP /mcp when your client supports MCP 2025-03-26; otherwise use /sse. First connection without a Bearer token triggers OAuth/PKCE in your browser. Approve the requested scopes in the HUMΛN Console; the client receives a session-scoped delegation.

What happens on first connect

  1. Client opens SSE without a token.
  2. Worker responds with WWW-Authenticate: Bearer realm="https://mcp.haio.run".
  3. Client generates a PKCE code_verifier, redirects you to https://console.haio.run/mcp/consent?code_challenge=....
  4. You log in (passkey) and approve the scope set.
  5. Console redirects with an auth_code.
  6. Client exchanges the code for a session-scoped delegation token.
  7. SSE stream opens. JSON-RPC messages flow.

Sessions are visible in Console → Settings → MCP Access. Revocation is one click.

What you get

Tier Tools
1 human.ask, human.companion.kb_search
2 human.intent, human.capability.discover, human.companion.chat
3 human.call + 12 REST proxies
4 (admin only — gated by cloud:admin:* scope)

Plus resources: human://kb/{doc_id}, human://schemas/{schema_name}.

Plus prompts: review-agent-manifest, design-delegation-scope.

Default scopes for a new session

The OAuth consent screen requests:

kb:read:public companion:chat

Add more scopes by reconnecting and approving an expanded grant. The Console can also pre-mint org-tier delegations for team members.

Rate limits

Plan tier Per-session/min Per-org/day
free 30 5,000
pro 120 50,000
business 600 500,000
enterprise configurable configurable

The Worker enforces these in KV. When you hit a limit, you get RFC 7807 429 with Retry-After and X-RateLimit-Reset.

Troubleshooting

  • 401 on first call: OAuth not completed. Look for the consent URL in the SSE error frame.
  • 403 insufficient_scope: Reconnect and approve a wider scope set.
  • 429: Hit the rate limit. Read X-RateLimit-Reset.
  • Connection closed unexpectedly: Network blip. Reconnect; the Worker holds session state for the OAuth grant lifetime.

Reference

  • Full tools: /ai/articles/mcp-tools-reference.md
  • Scope vocabulary: /ai/articles/delegation-scope-vocabulary.md
  • Intent modes: /ai/articles/companion-intent-modes.md
  • Guardrails: /ai/articles/guardrails-and-boundary-contracts.md

← All guides