Architecture (for reviewers)
Honest description of the API-token delegation model.
Components
| Component | Role |
|---|---|
| Claude connector client | OAuth public client (PKCE). Calls /mcp with shim-issued bearer tokens. |
| This OAuth shim | Authorization server + MCP reverse proxy. Issues OAuth tokens; stores mapping to HostAfrica API token. Also serves anonymous /domains/mcp. |
| HostAfrica MCP server | Authoritative MCP tool host. Validates HostAfrica bearer tokens. |
| Public domain MCP | /domains/mcp — no OAuth. tools/list is filtered to the two public domain tools; initialize instructions are domains-only; protected tools/call is rejected without a WWW-Authenticate challenge. |
Authorization model
This is API-token delegation, not HostAfrica-hosted login OAuth. During consent the user pastes an API token they generated at https://panel.hostafrica.com/public-api. The shim stores that token (encrypted at rest) and issues separate OAuth access/refresh tokens to Claude.
The connector supports mixed authentication: tools/list is always unauthenticated
discovery and must return the full catalog (public and protected tool names/schemas) from upstream. Public domain
tool calls work before OAuth; protected tool calls return HTTP 401 and trigger Connect. After consent, the shim validates
Claude's access token, swaps in the stored HostAfrica bearer token, and forwards the request unchanged to the
upstream MCP server.
Why this exists
Claude hosted connectors require OAuth metadata, PKCE, and refreshable tokens. The upstream HostAfrica MCP
server at https://api.hostafrica.com/mcp accepts bearer tokens directly. This shim bridges the
two protocols without modifying upstream tool code.