AppCrane MCP server

appcrane-mcp

The standalone MCP connector for AppCrane — the self-hosted deployment platform for AI-built, agent-deployed apps.

AppCrane exposes an MCP server at /api/mcp that requires an X-API-Key. This package is a thin stdio MCP server that:

1. Serves the full appcrane tool catalog for tools/list introspection with zero configuration** — it ships a bundled catalog.json, so registries and sandboxes (e.g. Glama) can start it in a container and introspect it offline.
2. Proxies real tools/call to your own AppCrane instance once APPCRANEURL and APPCRANEKEY are set.

It runs anywhere Node 20+ is available, via npx appcrane-mcp.

Licensing: this connector is MIT. The AppCrane platform it talks to is a separate

project and is AGPL-3.0. Installing this package does not pull the platform in — the

connector is a client that talks to an AppCrane instance you host yourself.

How you connect

There is no hosted service and no AppCrane account. The flow is entirely your own:

X-API-Key. Your key stays in your own MCP client config; it is never sent anywhere except the instance URL you set.

1. You self-host AppCrane (AGPL) somewhere you control.
2. You issue an API key from that instance.
3. Your agent runs this connector locally over stdio (npx -y appcrane-mcp).
4. The connector forwards each tools/call to ${APPCRANE_URL}/api/mcp with your

Install / run

npx appcrane-mcp

With no environment variables it still starts and answers tools/list from the bundled catalog (57 tools). To actually invoke tools against your instance, set:

MCP client configuration

This is a stdio command server (not an HTTP endpoint). Add it to your MCP client config like this:

{
  "mcpServers": {
    "appcrane": {
      "command": "npx",
      "args": ["-y", "appcrane-mcp"],
      "env": {
        "APPCRANE_URL": "https://crane.example.com",
        "APPCRANE_KEY": "your_api_key",
        "APPCRANE_GITHUB_TOKEN": "ghp_optional_for_github_passthrough"
      }
    }
  }
}

Claude Code CLI:

claude mcp add appcrane \
  --env APPCRANE_URL=https://crane.example.com \
  --env APPCRANE_KEY=your_api_key \
  -- npx -y appcrane-mcp

How it works

• tools/list
• If APPCRANEURL + APPCRANEKEY are set → connects to ${APPCRANEURL}/api/mcp (StreamableHTTP, header X-API-Key, plus X-Github-Token when the GitHub token is set), fetches the live, auth-filtered** tool list, and returns it. If the instance is unreachable it falls back to the bundled catalog.
• If not configured → returns the bundled static catalog (catalog.json). This path needs no env vars, which is what a registry's introspection sandbox hits.
• tools/call → requires APPCRANEURL + APPCRANEKEY; forwards the call to the backend and returns its result. Without configuration it returns a clear "not configured" error.

Docker

docker build -t appcrane-mcp .

# Introspection only (no config) — starts and serves tools/list:
docker run -i --rm appcrane-mcp

# Full use:
docker run -i --rm \
  -e APPCRANE_URL=https://crane.example.com \
  -e APPCRANE_KEY=your_api_key \
  appcrane-mcp

Development

npm install
npm run build          # tsc -> dist/
npm run gen:catalog    # regenerate catalog.json from the AppCrane platform source
npm run check:catalog  # fail if catalog.json has drifted from that source
node scripts/test-list.mjs   # smoke test: spawn over stdio, assert tools/list

Shortened. The full README is on GitHub.