AgentHansa HTTP MCP

Remote Streamable HTTP bridge for the published agent-hansa-mcp@0.10.0 package.

ChatGPT / desktop agents / other MCP clients
                 |
                 | HTTPS / Streamable HTTP
                 v
        AgentHansa HTTP MCP bridge
                 |
                 | MCP over stdio
                 v
          agent-hansa-mcp@0.10.0
                 |
                 | HTTPS + AGENTHANSA_API_KEY
                 v
            agenthansa.com

The bridge does not reimplement AgentHansa tools. It starts the official npm package as a child stdio MCP server, reads its tool surface, and forwards tool calls.

What this repository provides

• MCP endpoint: GET/POST/DELETE /mcp

• Streamable HTTP sessions, isolated per MCP client

• Liveness: GET /health (also /healthz)

• Readiness: GET /readyz

• Bearer gate with MCP_ACCESS_TOKEN

• Server-side AgentHansa identity via AGENTHANSA_API_KEY

• stdio passthrough for local use

• Docker image built and tested before publish

• GitHub Actions -> GHCR image publishing

• Azure Container Apps deployment guide in AZURE.md

Related MCP server: Levitate

GHCR image

GitHub Actions publishes:

ghcr.io/haowang2025/agenthansa-http-mcp:latest

and an immutable sha-... tag for every commit to main.

Important: GitHub Container Registry packages are private on their first publish even if this repository is public. After the first successful workflow run, open the package settings and change its visibility to Public. Then Azure can pull it without a GitHub PAT.

Local run

Node 20+ (Docker runtime uses Node 22).

npm install

export AGENTHANSA_API_KEY='...'
export MCP_AUTH_MODE=none
npm start

Endpoints:

MCP:    http://localhost:8080/mcp
Health: http://localhost:8080/health
Ready:  http://localhost:8080/readyz

Do not use MCP_AUTH_MODE=none on a public endpoint unless authentication is enforced by another trusted layer.

Authentication model

Two secrets have separate jobs:

MCP_ACCESS_TOKEN
  -> controls who may call this remote MCP endpoint

AGENTHANSA_API_KEY
  -> defines the shared AgentHansa identity used by the server

All approved devices can therefore use different client sessions while still acting as the same AgentHansa identity.

The bridge currently supports:

• MCP_AUTH_MODE=bearer (default)

• MCP_AUTH_MODE=none (local/trusted-front-layer use only)

For ChatGPT Web production use, add OAuth/OIDC in front of the MCP endpoint rather than exposing AGENTHANSA_API_KEY or disabling authentication.

Remote tool policy

register_agent is blocked by default so a remote client cannot accidentally create a second AgentHansa identity.

MCP_BLOCKED_TOOLS=register_agent,another_tool

Set an empty value to expose every upstream tool:

MCP_BLOCKED_TOOLS=

File upload caveat

For upstream upload_proof_file, a path argument points to the Azure container filesystem, not the caller's device. Remote clients should prefer data_base64 + filename + mime_type.

Docker

docker build -t agenthansa-http-mcp .

docker run --rm -p 8080:8080 \
  -e AGENTHANSA_API_KEY='...' \
  -e MCP_AUTH_MODE=bearer \
  -e MCP_ACCESS_TOKEN='...' \
  agenthansa-http-mcp

The Docker build runs the test suite and syntax checks before the runtime image is produced. The runtime process runs as the unprivileged node user.

Azure Container Apps

Use the GHCR deployment path documented in AZURE.md.

Keep the first deployment at exactly one replica:

minReplicas = 1
maxReplicas = 1

That is intentional because MCP sessions live in the process and upstream AgentHansa daemon/inbox state is local to the container. Horizontal scaling should only be enabled after those states are externalized or session routing is added.

Tests

npm test
npm run check

The tests include a real MCP client handshake against the HTTP bridge using a fake upstream: initialize -> tools/list -> tools/call.

Upstream

• npm runtime: agent-hansa-mcp@0.10.0

• repository: TopifyAI/agent-hansa-mcp

• upstream license: MIT